Fix dropped-item runtime gate policy

Align the specialized gate with the documented 5% effect-size rule while retaining confidence, MSPT, provenance, population, and candidate-work safeguards.

Author: Arbousier1

docs/phase2-performance-validation.md

@@ -361,7 +361,7 @@ Get-NetTCPConnection -OwningProcess $serverPid -LocalPort 25566 -State Establish
 - `displaySyncs`、`itemSyncs`、`virtualViewerChecks`。
 - 通用限流的 `visibilityShowsQueued`、`visibilityShowsDrained`；旧 `DroppedItemDisplay` 标签桶不使用这两个计数器。
 - `blockUpdateChecks`、`blockUpdateMs` 只统计各 display type 子 updater 的实际检查/更新调用；legacy parent collection iteration 和旧 task scheduling 不在该计时器内，必须从 MSPT/整体热路径判断。`Settings.Performance.BlockUpdates.MaxDirtyPerTick` 是每个 display type 的独立 dirty budget，不是所有熔炉类型共享的全局上限。
-- `itemAnimationMs`、`droppedItemMs`，需要除以 seconds、item 数和 viewer 数后比较。
+- `itemAnimationMs`、`droppedItemMs`，需要除以 seconds、item 数和 viewer 数后比较。`droppedItemMs` 是整个标签刷新 pass 的累计耗时，既包含候选来源，也包含对保留标签的格式化与 Paper metadata 更新；候选来源专项必须同时用 full-scan/spatial/viewer-check 计数证明复杂度变化，不能把整个 pass 的任意固定降幅当作候选查询本身的代理。
 
 `knownVirtualPackets` 是插件已知的顶层 Sparrow 调用/Bundle 数，不等于 Bundle 内逻辑包数、TCP segment 数或编码后字节。
 
@@ -435,6 +435,7 @@ $json = "D:\iv-ab\2026-07-13\S2_A_01.presentmon.json"
 - 静止动画锚点：`bukkitEntityTeleports` 至少下降 95%；`virtualTeleportBundles` 与 A 相差不超过 1%；客户端轨迹和拾取终点一致。
 - 通用 128/32 可见性：每玩家首个 drain tick show 不超过 128，后续每 tick 不超过 32；2048 个 `DisplayManager` 实体不超过 63 ticks 完成；`visibilityShowsQueued/Drained` 与去重、取消结果一致；50ms 峰值下行 payload 至少下降 70%，完整收敛窗口总 payload 与 A 相差不超过 5%。
 - 旧 dropped-label 128/32 回归：同样满足 128/32 与 63-tick 收敛上限，但使用真实标签的 Bukkit show/hide、ghost 检查和抓包计数，不得引用通用队列计数器作为证据。
+- dropped-item section candidate source：固定 2048 个全局跟踪 item、128 个 nearby label；B 的 full-scan 必须为 0，B 的 spatial candidates 与 viewer distance checks 各自不超过 A full-scan 的 10%。整个 `droppedItemMs` pass 仍按统一目标门执行：配对中位数至少改善 5%，且 bootstrap 95% CI 上界低于 ratio 1.0；MSPT 继续使用 1.02/1.05 守门。allocation profiler 仅用于归因，不能冒充 clean effect size。
 - 事件驱动 idle：1024 idle block 的相关 CPU/累计耗时至少下降 70%；100% active 的 p95/p99 不超过通用守门；标准事件在 2 ticks 内反映，非标准直接写入在约定 fallback audit 周期内修正。
 - FPS：p95 frame time 不恶化超过 2%，1% low 不下降超过 3%，且没有视觉正确性回归。
 

tools/perf/evaluate-dropped-item-gate.py

@@ -31,6 +31,9 @@
 FORMAL_RUN_COUNT = 12
 FORMAL_SAMPLING_MODE = "paired-adjacent"
 FORMAL_PAIR_COUNT = 6
+MINIMUM_TARGET_IMPROVEMENT = 0.05
+MAXIMUM_TARGET_MEDIAN_RATIO = 1.0 - MINIMUM_TARGET_IMPROVEMENT
+MAXIMUM_CANDIDATE_WORK_RATIO = 0.10
 
 
 def read_json(path: Path) -> dict[str, Any]:
@@ -468,8 +471,10 @@ def evaluate(manifest_path: Path, evidence_root: Path, expected_items: int,
     candidate_viewer_ratio = candidate_viewer_checks / baseline_full_scan
 
     checks = {
-        "droppedItemMedianRatioAtMost0_50": dropped["medianBRatioToA"] <= 0.50,
-        "droppedItemCiExcludesRegression": dropped["ratioBootstrap95Ci"][1] < 1.0,
+        "droppedItemMedianImprovementAtLeast5Percent":
+            dropped["medianBRatioToA"] <= MAXIMUM_TARGET_MEDIAN_RATIO,
+        "droppedItemBootstrap95CiUpperBelow1_00":
+            dropped["ratioBootstrap95Ci"][1] < 1.0,
         "msptP95CiUpperAtMost1_02": p95["ratioBootstrap95Ci"][1] <= 1.02,
         "msptP99CiUpperAtMost1_05": p99["ratioBootstrap95Ci"][1] <= 1.05,
         "allRunsRetainedGlobalPopulation": all(
@@ -482,18 +487,29 @@ def evaluate(manifest_path: Path, evidence_root: Path, expected_items: int,
             run["fullScanCandidates"] > 0 for run in runs if run["variant"] == "A"),
         "candidateTreatmentIsolated": all(
             run["sourceOwned"] is (run["variant"] == "B") for run in runs),
-        "candidateSpatialCandidatesAtMost10PercentOfBaseline": candidate_spatial_ratio <= 0.10,
-        "candidateViewerChecksAtMost10PercentOfBaseline": candidate_viewer_ratio <= 0.10,
+        "candidateSpatialCandidatesAtMost10PercentOfBaseline":
+            candidate_spatial_ratio <= MAXIMUM_CANDIDATE_WORK_RATIO,
+        "candidateViewerChecksAtMost10PercentOfBaseline":
+            candidate_viewer_ratio <= MAXIMUM_CANDIDATE_WORK_RATIO,
     }
     formal_complete = all(
         result.get("formalComplete") is True for result in analyses.values())
     passed = formal_complete and all(checks.values())
     gate = {
-        "schemaVersion": 2,
+        "schemaVersion": 3,
         "scenario": SCENARIO,
         "abFactor": AB_FACTOR,
         "formalComplete": formal_complete,
         "serverRuntimeGatePassed": passed,
+        "acceptancePolicy": {
+            "targetMetric": "droppedItemMs",
+            "minimumMedianImprovementPercent": MINIMUM_TARGET_IMPROVEMENT * 100.0,
+            "bootstrap95CiUpperMustBeBelow": 1.0,
+            "msptP95CiUpperAtMost": 1.02,
+            "msptP99CiUpperAtMost": 1.05,
+            "candidateWorkRatioAtMost": MAXIMUM_CANDIDATE_WORK_RATIO,
+            "basis": "docs/phase2-performance-validation.md section 7",
+        },
         "workload": {
             "trackedItems": expected_items,
             "nearbyLabels": expected_nearby_items,
@@ -532,9 +548,11 @@ def evaluate(manifest_path: Path, evidence_root: Path, expected_items: int,
                 f"Workload: `{expected_items}` tracked / `{expected_nearby_items}` nearby labels.\n\n")
             stream.write(
                 f"droppedItemMs B/A: `{dropped['medianBRatioToA']}` "
-                f"(95% CI `{dropped['ratioBootstrap95Ci']}`).\n\n")
+                f"(95% CI `{dropped['ratioBootstrap95Ci']}`; required median "
+                f"`<= {MAXIMUM_TARGET_MEDIAN_RATIO:.2f}` and CI upper `< 1.0`).\n\n")
             stream.write(
-                f"Candidate/full-scan ratio: `{candidate_spatial_ratio:.6f}`.\n\n")
+                f"Candidate/full-scan ratio: `{candidate_spatial_ratio:.6f}` "
+                f"(required `<= {MAXIMUM_CANDIDATE_WORK_RATIO:.2f}`).\n\n")
             stream.write(
                 f"MSPT p95 CI upper: `{p95['ratioBootstrap95Ci'][1]}`; "
                 f"p99 CI upper: `{p99['ratioBootstrap95Ci'][1]}`.\n")
@@ -700,7 +718,7 @@ def write_manifest() -> None:
         write_manifest()
 
         analysis_parameters = {
-            "droppedItemMs": (0.40, [0.35, 0.45]),
+            "droppedItemMs": (0.90, [0.85, 0.94]),
             "msptP95": (0.99, [0.98, 1.01]),
             "msptP99": (1.00, [0.99, 1.04]),
         }
@@ -773,9 +791,35 @@ def write_analyses() -> None:
         summary = os.environ.pop("GITHUB_STEP_SUMMARY", None)
         try:
             gate = evaluate(manifest_path, root, 2_048, 128, root / "gate.json")
+            assert gate["schemaVersion"] == 3
             assert gate["serverRuntimeGatePassed"] is True
+            assert gate["checks"]["droppedItemMedianImprovementAtLeast5Percent"] is True
+            assert gate["checks"]["droppedItemBootstrap95CiUpperBelow1_00"] is True
             assert gate["ratios"]["candidateSpatialToBaselineFullScan"] == 0.0625
 
+            analysis_parameters["droppedItemMs"] = (0.96, [0.92, 0.99])
+            write_analyses()
+            small_effect_gate = evaluate(
+                manifest_path, root, 2_048, 128, root / "small-effect-gate.json")
+            assert small_effect_gate["serverRuntimeGatePassed"] is False
+            assert small_effect_gate["checks"][
+                "droppedItemMedianImprovementAtLeast5Percent"] is False
+            assert small_effect_gate["checks"][
+                "droppedItemBootstrap95CiUpperBelow1_00"] is True
+
+            analysis_parameters["droppedItemMs"] = (0.90, [0.85, 1.01])
+            write_analyses()
+            uncertain_effect_gate = evaluate(
+                manifest_path, root, 2_048, 128, root / "uncertain-effect-gate.json")
+            assert uncertain_effect_gate["serverRuntimeGatePassed"] is False
+            assert uncertain_effect_gate["checks"][
+                "droppedItemMedianImprovementAtLeast5Percent"] is True
+            assert uncertain_effect_gate["checks"][
+                "droppedItemBootstrap95CiUpperBelow1_00"] is False
+
+            analysis_parameters["droppedItemMs"] = (0.90, [0.85, 0.94])
+            write_analyses()
+
             declining_metrics_path = run_roots[0] / "iv-perf.json"
             declining_metrics = read_json(declining_metrics_path)
             declining_metrics["droppedTrackedItemsMin"] = 2_047
@@ -864,6 +908,9 @@ def write_analyses() -> None:
     print(json.dumps({
         "passed": True,
         "analysisSchemaVersion": 2,
+        "gateSchemaVersion": 3,
+        "documentedEffectSizeGate": True,
+        "confidenceIntervalImprovementGate": True,
         "canonicalWindowGate": True,
         "analysisEvidenceClosure": True,
         "mixedStackPaperClientRejected": True,