DimensionalRipper/docs/superpowers/plans/2026-10-06-payload-ownership.md

公共收包线程归属 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 将受支持的服务端游戏包交给真正主线程独占处理，修复把手松开路径，同时保留阶段之外的维度并行。

Architecture: 每服务器有界 FIFO 接收显式主线程工作；服务器外层 tick 建立全维度安全阶段，批量调用原处理器。阶段状态阻止递归收口和新增维度写入，旧组装入口复用同一执行权。生命周期清理与通用包失效分开处理。

Tech Stack: Java 21、Minecraft 1.21.1、NeoForge、Mixin/MixinExtras、现有 Gradle 隔离服务器回归。

Spec: docs/superpowers/specs/2026-10-06-payload-ownership-design.md

执行状态（2026-10-06）： Task 1 已提交 691e949；Task 2–5 的公共入口、阶段、适配与诊断代码已实施并有回归证据。Task 4 的完整原生资源异常清理矩阵、Task 5 的双服务器压力测试、Task 6 的完整性能/客户端矩阵未全部验收，因此不勾选混合这些要求的条目。具体通过项和剩余项以 docs/payload-ownership-1.1.17-validation.md 为准，本轮只交付候选包。

Global Constraints

• 第一版新公共入口默认全维度隔离，不凭“玩家当前维度”或包内坐标猜测整个处理器的访问范围。
• 初始批次上限为 64 项或 2 ms 的处理时间，达到任一条件后不启动下一项；不强行中断已开始的处理器。
• 服务器队列上限 4096 项、单连接上限 256 项。
• 记录上限 128 个 ID，超出归入 other，避免恶意 ID 撑大统计。
• 登录、握手、配置阶段、客户端接收和纯网络线程处理不被无条件改派。
• 超时用于诊断，不是允许并发执行的理由。
• 不自动上传远端或部署正式服务器。测试仅操作仓库隔离世界或显式创建的存档副本。
• 不改变原处理器权限、距离、强加载规则；不放松 Level 的线程守卫。
• ServerWarashi 是后续独立修复，需要单独的采样设计及失败测试；本计划不宣称解决该崩溃。
• C2ME、后台光照查询及既有停服超时不纳入修复声明。

Review Focus

• 主线程正在服务等待中的 Sable 回调时再次 enqueue：不得等待该回调所属 worker，任务 2、3 验证。
• 前一个包传送/替换玩家后，同连接后续旧包不得操作新世界：任务 3、4 验证。
• 嵌套调用导致新世界/循环出现：不得在独占期间启动另一个写入者，任务 2 验证。
• 队列满载时恰好收到松手：拒绝要显式完成 future，断线清理不能遗留约束，任务 1、4 验证。
• 停服与阶段 finally、开关/菜单暂停同时发生：不得恢复已停止或仍应暂停的循环，任务 2、5 验证。

执行与证据约定

当前工作树含尚未提交的 1.1.16 归属修复，不能用新 worktree 的裸 HEAD 替代这些依赖。执行开始按 worktree 技能检查隔离方式；保留并核对所有现有变更，禁止 reset 或覆盖。不把原有未验证内容顺手算作本次通过。

以下路径相对仓库根。每个任务先写断言、记录失败，再改生产代码；每任务结束显式暂存该任务文件并提交（git 使用本仓库 safe.directory）。混合文件先核对 diff，不能误纳入用户后续改动。

命令统一使用 Java 21、--no-daemon --no-configuration-cache --console=plain。新的 -PpayloadRegression 夹具与 ownershipRegression、interactionRegression 互斥；运行结束必须有全部指定 PASS 标记且没有 unexpected exception，不能仅依赖进程退出码。证据放 build/reports/payload/。

文件职责

• core/compat/PayloadWorkQueue.java：不依赖 Minecraft 的 FIFO、容量、取消及批次预算。
• core/compat/MainThreadPhaseCoordinator.java：服务器阶段状态与独占租约。
• core/compat/PayloadMainThreadDispatch.java：实际玩家上下文、future、生命周期与 drain。
• core/compat/PayloadDiagnostics.java：有界计数及耗时快照。
• mixin/ServerPayloadContextMixin.java：两个 enqueueWork 重载，保留原有分支及 guard。
• mixin/MinecraftServerPayloadMixin.java：外层 tick 的 drain，不扩展到通用 pollTask。
• 已有 ServerManager、LevelTickLoop、Sable 桥、组装兼容、停止入口：接入阶段生命周期。
• tests/PayloadWorkQueueRegression.java：纯 Java 队列测试。
• tests/payload/PayloadRegression.java：实际 NeoForge 上下文与多维度集成。
• tests/payload/SimulatedHandleRegression.java：可选真实模组处理器及约束清理测试。

Task 1: 可测试的有界队列

Files: 创建 src/main/java/dev/modzuozhi/core/compat/PayloadWorkQueue.java、tests/PayloadWorkQueueRegression.java；修改 build.gradle。

Interfaces: PayloadWorkQueue<K>(LongSupplier nanoTime)；<T> CompletableFuture<T> submit(K connection, Supplier<T> action)；int drainBatch()；void close(Throwable reason)；int size()。拒绝返回异常 future；执行前已取消的任务不产生副作用。锁只保护队列及计数，绝不包住 action 或 completion 回调。

• 写 fifoAndExactlyOnce、capacityAndCancellation、batchCountAndTime、closeAndReentrantCompletion 断言：同连接顺序 0..255；第 257 项拒绝；16 个连接各 256 项填满后第 4097 项拒绝；取消使容量回收；批次最多 64；假时钟到 2_000_000 ns 后不再启动下一项；慢 action 不被中断；close 后旧 future 全结束且不能再接收。
• 添加 runPayloadWorkQueueRegression 到 check；先运行并保存失败证据，不能以无测试发现作为 RED。
• 实现上述接口；future 完成回调可重新 submit/close 而无锁死；Supplier 异常只影响本项。
• 运行 ./gradlew.bat runPayloadWorkQueueRegression，输出 PAYLOAD QUEUE PASS；并行提交/取消压力测试核对计数为零。
• 审阅并提交本任务文件。

Task 2: 安全阶段与循环生命周期

Files: 创建 src/main/java/dev/modzuozhi/core/compat/MainThreadPhaseCoordinator.java、tests/payload/PayloadRegression.java；修改 core/dimthread/ServerManager.java、core/dimthread/LevelTickLoop.java、core/compat/SableMainThreadBridge.java（均位于 src/main/java/dev/modzuozhi/），修改 build.gradle。

Interfaces: coordinator 的 void run(MinecraftServer server, String reason, Runnable action)、boolean owns(MinecraftServer server)、boolean blocksWorkerStart(MinecraftServer server)、void stopping(MinecraftServer server)、void clear(MinecraftServer server)；Sable 桥新增 boolean inHandoff(MinecraftServer server)。ServerManager.runMainThreadPhase 委托 coordinator，保持现有 CC 调用不变。

• 写 exclusivePhase、nestedPhase、handoffReentryRejected、newLoopDuringPhase、stopDuringPhase：处理期间全部世界 owner 为真主线程、worker 写入计数不增加；等待可完成 Sable 回调；独占内嵌套只建一次屏障；handoff 中建全局屏障立即明确失败；新 loop 在阶段退出前不能开跑；预先暂停、菜单暂停、停止状态不被 finally 恢复。
• ./gradlew.bat runServer -PpayloadRegression 得到预期断言失败，保存日志；夹具另用超时终止测试而非让生产代码越过屏障。
• 实现 IDLE/DRAINING/EXCLUSIVE/RESTORING/STOPPING 状态、租约与入口检查。循环注册、scheduleIfNeeded、resume 共享阶段启动门禁；新 loop 参与退出处理。等待不持锁，继续 pump 必要回调；嵌套 drain 不递归。循环已经在途时等待其子任务及线程字段全部归还。
• 运行夹具输出 PAYLOAD PHASE PASS；复跑 ownershipRegression，确认 CC 预置暂停及 Sable 回调仍通过。
• 审阅并提交本任务文件。

Task 3: NeoForge 公共入口与 future 语义

Files: 创建 src/main/java/dev/modzuozhi/core/compat/PayloadMainThreadDispatch.java、src/main/java/dev/modzuozhi/mixin/ServerPayloadContextMixin.java、src/main/java/dev/modzuozhi/mixin/MinecraftServerPayloadMixin.java；修改 tests/payload/PayloadRegression.java、src/main/resources/dimensionalripper.mixins.json。

Interfaces: dispatch 的 <T> CompletableFuture<T> submit(ServerPlayer player, ResourceLocation payloadId, Supplier<T> action)、boolean owns(MinecraftServer server)、void drain(MinecraftServer server)、void stop(MinecraftServer server)。Runnable 适配 Supplier。任务保存实际 connection、player、接收时 ServerLevel 身份及时间；各服务器实例独立。

• 用真实 ServerPayloadContext 的 Runnable/Supplier 路径写 mainPayloadSeesBlockEntity、futureContract、phaseEscapeAndStalePlayer、configurationPassthrough。断言并发维度下能取得原 BE、true main、至多一次；Supplier 返回 42；异常、取消和 guard 的对外结果与未修改 NeoForge 一致，内部真实失败仍可见；权限拒绝未发生世界变更；配置阶段不调用 player()；网络计算原线程不变。
• 运行 payloadRegression 记录原入口 wrong-owner/null 的失败；记录尚未覆盖的真实 Veil 路径，不冒充实测。
• 两个 enqueueWork 仅拦截游戏玩家的显式主线程工作。网络/worker 投递不等待；独占内嵌套立即完成；普通主线程外层进入安全阶段时先遵守同连接已排队顺序；DRAINING 中普通投递只入队；同步 handoff 重入按任务 2 契约明确失败。原 handler、上下文与 NetworkRegistry.guard 保留，不双重执行。
• 在 MinecraftServer.tickServer HEAD 的外层主线程 drain 一批；不在 pollTask 或 worker 回调内 drain。执行前验证连接、player 身份及世界；失效 future 明确结束。无队列不建屏障。
• 加 workerWaitCycleDetected 测试：worker 等待队列 future 时测试必须识别无法收口且取消夹具，不误报自动兼容。运行集成输出 PAYLOAD ENTRY PASS，覆盖没有并行 loop 的原版情况。
• 审阅并提交本任务文件。

Task 4: 原模组交互与清理路径

Files: 修改 src/main/java/dev/modzuozhi/core/compat/SableAssemblyDispatch.java、src/main/java/dev/modzuozhi/mixin/CreateConfigurationPacketMixin.java、src/main/java/dev/modzuozhi/mixin/SimulatedAssemblePacketMixin.java；创建 tests/payload/SimulatedHandleRegression.java；修改 build.gradle。若真实路径证明需要专用适配，仅新增 src/main/java/dev/modzuozhi/mixin/JadeRequestDispatchMixin.java 与 src/main/java/dev/modzuozhi/mixin/SimulatedHandleLifecycleMixin.java，并登记可选 mixin。

Interfaces: 保持 SableAssemblyDispatch.dispatch(ServerPlayer,Runnable)，改为复用公共阶段/投递，禁止再送进已暂停的维度队列。具体可选模组方法描述符从本地实际 jar 审计后锁定，不能猜注入目标。

• 先记录真实 UpdatePlayerUsingHandlePacket.handle 的抓取、距离、松手入口、BE 身份、HandleConstraint 移除结果，建立 RED。核对 HandleBlockEntity.checkPlayers 及断线/死亡/卸载清理，不仅测试模拟 Runnable。
• 审计 Veil 注册和 Jade 二次 server.execute；建立逃逸测试。只有已观察的逃逸点使用定点包装，不改写全部 MinecraftServer.execute。旧 Create/组装入口在公共独占内直接调用原 handler；阶段外走相同队列。
• 测试顺序与副作用：抓取一次、更新距离一次、松手一次，最后 constraint 不存在；两个玩家不会互相释放；转速配置、组装拆解保留原权限和距离行为，错误坐标不强加载。
• 覆盖断线、换维度、死亡、把手拆除、sublevel 卸载和单连接 256 满载后松手被拒绝；若原清理不足，可信生命周期适配在旧世界安全阶段释放资源，不重放过期客户端包。过载断开连接调用原 disconnect/cleanup，日志限频。
• 真实运行输出 SIMULATED HANDLE PASS、CREATE CONFIG PASS、JADE REQUEST PASS。原模组依赖或原生物理无法启动时，记录未通过项并暂停“把手已修复”的交付结论，不能用假夹具替代。
• 审阅并提交已验证的适配文件；无必要不创建专用 mixin。

Task 5: 停止、可观测性与限频

Files: 创建 src/main/java/dev/modzuozhi/core/compat/PayloadDiagnostics.java；修改 src/main/java/dev/modzuozhi/core/compat/PayloadMainThreadDispatch.java、src/main/java/dev/modzuozhi/mixin/MinecraftServerDimMixin.java、src/main/java/dev/modzuozhi/core/compat/ThreadOwnershipDiagnostics.java、src/main/java/dev/modzuozhi/command/MasterCommand.java、tests/payload/PayloadRegression.java。

Interfaces: PayloadDiagnostics.snapshot(MinecraftServer server): String，只读且不新建循环；dispatch.stop 拒绝接收、终结待执行 future，阶段退出不恢复停止中的 loop；clear 在清理结束移除服务器引用。

• 写 boundedDiagnostics、stopRejectsAndReleases、twoServersIsolated：1000 个不同 ID 最多 128 个具名项加 other；1000 次失败不输出1000份堆栈；停止后无遗留 future/连接/世界引用；某一服务器 stop 不影响另一服务器。
• 运行得到 RED。实现每服务器计数、队列最老等待、最近 32 事件、等待/执行耗时、批次数；异常全局 30 秒限频，快照无包正文。正常/异常停止入口在既有循环停止与保存之前关闭新队列；不要把旧 30 秒停服风险说成已解决。
• status 和 crash report 附快照，区分等待 worker、handler 慢和 Sable handoff；测试所有失败 future 最终完成且 handler 从不重复执行。
• 运行 payloadRegression 输出 PAYLOAD LIFECYCLE PASS、PAYLOAD DIAGNOSTICS PASS，审阅并提交。

Task 6: 兼容验收与候选包

Files: 修改 README.md、gradle.properties（候选版本 1.1.17）；证据 build/reports/payload/。

Interfaces: 交付明确列出“源码/字节码审计”“夹具通过”“真实模组通过”的覆盖表，不将它们合并为兼容保证。

• 分别运行 ./gradlew.bat check、runServer -PpayloadRegression、runServer -PownershipRegression -PccTestJar=<已验证本地CC路径>、runServer -PinteractionRegression。逐项确认纯 Java、CC、区块、水流、实体路由和新 PASS 标记，不把预期故障夹具当成功事故。
• 无 Create/Veil/Jade/Simulated 可选模组启动通过；真实模组组合另跑，不自动复制到用户 mods 目录。
• 对比无交互、普通交互、密集抓握、多人查询及慢维度：主线程 TPS、维度完成 TPS、队列延迟、阶段耗时。无交互新增屏障数必须为零；报告慢维度代价，不以 Carpet MSPT 独立判定。
• 正常构建 ./gradlew.bat clean build，不带任何夹具属性。检查 jar 无 tests/Regression/测试模组类、元数据 1.1.17，记录 SHA256。
• 按 requesting-code-review 技能审查完整差异，修复阻塞问题并重跑受影响测试。README 清楚标注 ServerWarashi 仍未由本计划修复以及真实航空学验收状态；提交本任务。
• 只交付本地候选 jar 和覆盖/风险说明；如真实物理未通过，交付测试候选而非宣称全部修好。不推远端、不部署。

自审结果

设计第 4 节对应任务 1–3；旧适配、Veil/Jade 与生命周期对应任务 4–5；有界诊断与性能/打包对应任务 5–6。所有五个 Review Focus 已映射到断言。ServerWarashi 明确作为独立后续工作，不以当前方案替代采样栈修复。