From 920efc36f7de100a864fe9d09848c5bb51d3bd2a Mon Sep 17 00:00:00 2001
From: Kinneyzhang <kinneyzhang666@gmail.com>
Date: Mon, 7 Sep 2026 04:09:50 +0800
Subject: [PATCH] docs: align batch and GUI performance evidence contracts

---
 DESIGN.md       |  5 +++--
 DESIGN.zh-CN.md | 23 +++++++++++++----------
 README.md       |  7 ++++---
 3 files changed, 20 insertions(+), 15 deletions(-)

diff --git a/DESIGN.md b/DESIGN.md
index acd4d53..8d8fd17 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -205,10 +205,11 @@ triplet.
 
 ## Performance evidence lanes
 
-The batch regression lane, trace lane, and GUI lane share one
+The batch latency lane, trace lane, and GUI lane share one
 repository/environment/scenario/fixture/build identity but remain separate
 measurements. The retained Research Shelf 1413×62 batch evaluator owns its
-uninstrumented 5/30 p95/max 50ms regression checks.
+uninstrumented 5/30 p95/max 50ms regression checks. Batch verifier duration
+measures batch Lisp work, not GUI first paint.
 The trace lane owns a representative instrumented invocation with cost class,
 work counters, turns, allocation, and GC. The GUI lane owns the real Emacs
 action sequence and reviewed visual evidence. Current GUI acceptance additionally
diff --git a/DESIGN.zh-CN.md b/DESIGN.zh-CN.md
index d7095a0..eeec1a6 100644
--- a/DESIGN.zh-CN.md
+++ b/DESIGN.zh-CN.md
@@ -108,9 +108,10 @@ ETAF 私有 registry 变量；Component setup 中创建的 Controller 自动归
 - 用 inert reader、source tab/session、未保存 source refresh 和 SQLite 临时文件
   测试 mount/remount、筛选、分页、重复选行、mutation、错误状态和 cleanup；GUI
   用干净 fullscreen 截图验证真实布局。
-- 目标：一次 Data mutation 对应一次 Runtime generation/publication。当前有效的
-  延迟 lane 在固定 1413×62 几何下执行 5 次未计时 warmup 与 30 个计时 sample，
-  每个场景的 p95 和 max 均须不超过 50ms。已接受的 105ms p50 是历史设计上下文，
+- 目标：一次 Data mutation 对应一次 Runtime generation/publication。Research Shelf
+  的批处理延迟 lane 在固定 1413×62 几何下执行 5 次未计时 warmup 与 30 个计时 sample，
+  每个场景的 p95 和 max 均须不超过 50ms；当前 GUI 验收还有下述独立要求。
+  已接受的 105ms p50 是历史设计上下文，
   不是当前 evaluator gate；其正式处置仍由 M0b1 的 `DOC-PERF-001` 负责。
 - 压测入口：`etaf-research-shelf-fixture-size` 默认 256，
   `etaf-research-shelf-page-size` 默认 12；已有本地记录保留，不足部分使用新 ID
@@ -118,13 +119,15 @@ ETAF 私有 registry 变量；Component setup 中创建的 Controller 自动归
 
 ## 性能 evidence lanes
 
-延迟 lane、追踪 lane 与 GUI lane 共享同一组仓库、环境、场景、fixture 和 build identity，
-但保持为三种独立测量。延迟 lane 负责无 instrumentation 的 5/30、p95/max 50ms
-门禁；追踪 lane 负责一次代表性 instrumented invocation 的 cost class、work counters、
-turns、allocation 与 GC；GUI lane 负责真实 Emacs action sequence、截图、录像与
-temporal-review verdict。Batch verifier duration 不是 GUI first paint；从 action-start
-到 forced redisplay completion 的 first-paint 计时仍是独立 future gate，也是 M0a
-明确记录的 observed gap。任何一条 lane 都不能替另一条 lane 宣称通过。
+批处理延迟 lane、追踪 lane 与 GUI lane 共享同一组仓库、环境、场景、fixture 和 build identity，
+但保持为三种独立测量。批处理延迟 lane 负责 Research Shelf 1413×62 fixture 中
+无 instrumentation 的 5/30、p95/max 50ms 回归检查。Batch verifier duration
+不是 GUI first paint。追踪 lane 负责一次代表性 instrumented invocation 的 cost class、
+work counters、turns、allocation 与 GC；GUI lane 负责真实 Emacs action sequence
+与已审查的画面证据。当前 GUI 验收还要求三组独立的前台实测，每项操作从回调开始
+到强制 redisplay 返回的 p95 和 max 均不超过 50ms；该门禁尚未通过。使用
+`../etaf/scripts/README.md` 中的测量入口，保留预热、GC 记录和全部样本。
+redisplay 返回不能证明操作系统已经呈现画面。任何一条 lane 都不能替另一条 lane 宣称通过。
 
 ## 待 review
 
diff --git a/README.md b/README.md
index ae48885..6fc7cff 100644
--- a/README.md
+++ b/README.md
@@ -148,7 +148,7 @@ missing recording, wrong buffer, split window, stale frame, or missing temporal
 review remains fail-closed.
 
 Run `make check EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs`.
-Run `make perf` for the fixed 1413×62 latency gate. Every scenario performs
+Run `make perf` for the fixed 1413×62 batch latency gate. Every scenario performs
 five unmeasured warmups followed by 30 measured samples; both p95 and max must
 remain at or below 50ms, including Theme and post-resize interactions.
 For repeated absolute-latency runs, use `make perf-prepare` once after source
@@ -160,9 +160,10 @@ rebuilding the dependency graph.
 Performance evidence has three separate lanes correlated by one
 repository/environment/scenario/fixture/build identity:
 
-- The batch regression lane runs the retained Research Shelf 1413×62 evaluator
+- The batch latency lane runs the retained Research Shelf 1413×62 evaluator
   with 5 unmeasured warmups and 30 measured samples. Its p95/max 50ms checks
-  diagnose regressions in that batch fixture.
+  diagnose regressions in that batch fixture. Batch verifier duration measures
+  batch Lisp work, not GUI first paint.
 - The trace lane runs a separate instrumented representative invocation. Its
   cost classes, work counters, turns, allocation, and GC data are not inserted
   into the timed latency distribution.