Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

docs(scale): describe the one-stall rule of the import-rate gate (#7939)

garrytan36c15cbbf56e
diff --git a/scripts/scale/README.md b/scripts/scale/README.md
index ed26c48222..cdb4e5f4e9 100644
--- a/scripts/scale/README.md
+++ b/scripts/scale/README.md
@@ -43,8 +43,17 @@ its EXPLAIN; the JSON report and a `.explain.txt` land next to `--out`);
2 on a usage error; 3 when the harness itself crashed (not a verdict).
The import-rate gate compares the last 10% of pages' per-page cost with the
first 10% (<= 1.5x) and the total import with the time at the halfway mark
-(<= 2.5x). The report and its JSON `import` section carry both bases for every
-engine: wall time (`elapsed_ms`) and the import process's main-thread CPU time
+(<= 2.5x). Both ratios set aside at most one stall per import (#7939): a
+paused database container or a WAL checkpoint lands in one page's time and
+once failed unrelated pull requests on its own. Each tenth is cut into ten
+slices; the slice with the largest excess over its tenth's median slice is
+lowered to the next-largest excess anywhere in the import, and its tenth
+never drops below the Theil-Sen line through the ten tenth means. Work that
+recurs (a rebuild every few hundred pages, or once per tenth) is kept at the
+plain measure's sensitivity; only the margin of its largest occurrence over
+the next one can be set aside. The gate message names the stall and the
+report's `import.<basis>.excused` records it. The report and its JSON
+`import` section carry both bases for every engine: wall time (`elapsed_ms`) and the import process's main-thread CPU time
(`cpu_ms`, user + system, from each progress tick; in-process timing under
`--import-mode content`). PGLite is judged on CPU time: the database runs
synchronously on the import's main thread, so that CPU time holds all of its