@maverickcer/env-cap 0.7.5 → 0.7.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (278) hide show
  1. package/ADOPTION.md +12 -12
  2. package/AGENTS.md +85 -120
  3. package/CHANGELOG.md +27 -0
  4. package/CODE_REVIEW.md +5 -5
  5. package/CONTRIBUTING.md +5 -5
  6. package/GUIDE.md +42 -24
  7. package/README.md +52 -34
  8. package/RELEASING.md +78 -64
  9. package/SECURITY.md +15 -15
  10. package/VERSIONING.md +16 -15
  11. package/benchmarks/READING-BENCHMARKS.md +101 -85
  12. package/benchmarks/README.md +12 -9
  13. package/benchmarks/WRITING-BENCHMARKS.md +89 -79
  14. package/benchmarks/performance-buildtime/BENCHMARKS.md +20 -20
  15. package/benchmarks/performance-runtime/BENCHMARKS.md +107 -107
  16. package/dist/.dts/_ipc/build-fs.d.ts +3 -3
  17. package/dist/.dts/_ipc/build-fs.d.ts.map +1 -1
  18. package/dist/.dts/_ipc/display-path.d.ts +1 -1
  19. package/dist/.dts/_ipc/glob.d.ts +3 -2
  20. package/dist/.dts/_ipc/glob.d.ts.map +1 -1
  21. package/dist/.dts/_ipc/no-node-fs.d.ts +2 -2
  22. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  23. package/dist/.dts/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  24. package/dist/.dts/_ipc/typescript.d.ts +4 -4
  25. package/dist/.dts/build/assemble-project.d.ts +14 -15
  26. package/dist/.dts/build/assemble-project.d.ts.map +1 -1
  27. package/dist/.dts/build/change-model.d.ts +14 -14
  28. package/dist/.dts/build/change-model.d.ts.map +1 -1
  29. package/dist/.dts/build/check-artifacts.d.ts +4 -4
  30. package/dist/.dts/build/check-artifacts.d.ts.map +1 -1
  31. package/dist/.dts/build/citation-verification.d.ts +13 -14
  32. package/dist/.dts/build/citation-verification.d.ts.map +1 -1
  33. package/dist/.dts/build/compatibility.d.ts +24 -24
  34. package/dist/.dts/build/compatibility.d.ts.map +1 -1
  35. package/dist/.dts/build/contract-model.d.ts +10 -10
  36. package/dist/.dts/build/contract-model.d.ts.map +1 -1
  37. package/dist/.dts/build/deep-equal.d.ts +2 -2
  38. package/dist/.dts/build/deep-freeze.d.ts +2 -2
  39. package/dist/.dts/build/dependency-graph.d.ts +48 -55
  40. package/dist/.dts/build/dependency-graph.d.ts.map +1 -1
  41. package/dist/.dts/build/dependency-model.d.ts +18 -18
  42. package/dist/.dts/build/dependency-model.d.ts.map +1 -1
  43. package/dist/.dts/build/discover.d.ts +11 -11
  44. package/dist/.dts/build/discover.d.ts.map +1 -1
  45. package/dist/.dts/build/docs.d.ts +34 -38
  46. package/dist/.dts/build/docs.d.ts.map +1 -1
  47. package/dist/.dts/build/env-example.d.ts +13 -13
  48. package/dist/.dts/build/env-example.d.ts.map +1 -1
  49. package/dist/.dts/build/errors.d.ts +8 -8
  50. package/dist/.dts/build/evidence-cache.d.ts +23 -23
  51. package/dist/.dts/build/evidence-cache.d.ts.map +1 -1
  52. package/dist/.dts/build/evidence-model.d.ts +3 -3
  53. package/dist/.dts/build/evidence-reference.d.ts +15 -15
  54. package/dist/.dts/build/evidence-reference.d.ts.map +1 -1
  55. package/dist/.dts/build/evidence-snapshot.d.ts +47 -53
  56. package/dist/.dts/build/evidence-snapshot.d.ts.map +1 -1
  57. package/dist/.dts/build/exclusive-group.d.ts +4 -4
  58. package/dist/.dts/build/exclusive-group.d.ts.map +1 -1
  59. package/dist/.dts/build/finding-model.d.ts +12 -12
  60. package/dist/.dts/build/finding-model.d.ts.map +1 -1
  61. package/dist/.dts/build/generate-documentation.d.ts +19 -19
  62. package/dist/.dts/build/generate-documentation.d.ts.map +1 -1
  63. package/dist/.dts/build/generate-env-artifacts.d.ts +43 -43
  64. package/dist/.dts/build/generate-env-artifacts.d.ts.map +1 -1
  65. package/dist/.dts/build/generate-evidence.d.ts +19 -19
  66. package/dist/.dts/build/generate-evidence.d.ts.map +1 -1
  67. package/dist/.dts/build/generate-manifest.d.ts +11 -12
  68. package/dist/.dts/build/generate-manifest.d.ts.map +1 -1
  69. package/dist/.dts/build/generate-usage.d.ts +23 -24
  70. package/dist/.dts/build/generate-usage.d.ts.map +1 -1
  71. package/dist/.dts/build/generated-banner.d.ts +5 -5
  72. package/dist/.dts/build/governance-fields.d.ts +7 -7
  73. package/dist/.dts/build/humanize-key.d.ts +1 -1
  74. package/dist/.dts/build/humanize-key.d.ts.map +1 -1
  75. package/dist/.dts/build/index.d.ts +20 -36
  76. package/dist/.dts/build/index.d.ts.map +1 -1
  77. package/dist/.dts/build/lifecycle-model.d.ts +87 -85
  78. package/dist/.dts/build/lifecycle-model.d.ts.map +1 -1
  79. package/dist/.dts/build/link.d.ts +38 -39
  80. package/dist/.dts/build/link.d.ts.map +1 -1
  81. package/dist/.dts/build/literal-eval.d.ts +2 -2
  82. package/dist/.dts/build/literal-eval.d.ts.map +1 -1
  83. package/dist/.dts/build/live-expirations.d.ts +14 -13
  84. package/dist/.dts/build/live-expirations.d.ts.map +1 -1
  85. package/dist/.dts/build/manifest.d.ts +6 -6
  86. package/dist/.dts/build/map-utils.d.ts +4 -4
  87. package/dist/.dts/build/merge-documentation.d.ts +9 -8
  88. package/dist/.dts/build/merge-documentation.d.ts.map +1 -1
  89. package/dist/.dts/build/ownership-model.d.ts +14 -15
  90. package/dist/.dts/build/ownership-model.d.ts.map +1 -1
  91. package/dist/.dts/build/parse.d.ts +20 -21
  92. package/dist/.dts/build/parse.d.ts.map +1 -1
  93. package/dist/.dts/build/reference-projections.d.ts +36 -38
  94. package/dist/.dts/build/reference-projections.d.ts.map +1 -1
  95. package/dist/.dts/build/resolution/resolve-import.d.ts +18 -14
  96. package/dist/.dts/build/resolution/resolve-import.d.ts.map +1 -1
  97. package/dist/.dts/build/resolution/resolve-package-schema.d.ts +26 -26
  98. package/dist/.dts/build/resolution/resolve-package-schema.d.ts.map +1 -1
  99. package/dist/.dts/build/resolution/resolve-within-root.d.ts +9 -9
  100. package/dist/.dts/build/sarif.d.ts +5 -5
  101. package/dist/.dts/build/sarif.d.ts.map +1 -1
  102. package/dist/.dts/build/scan-dependencies.d.ts +17 -16
  103. package/dist/.dts/build/scan-dependencies.d.ts.map +1 -1
  104. package/dist/.dts/build/sort-by-identity.d.ts +1 -1
  105. package/dist/.dts/build/source-position.d.ts +13 -13
  106. package/dist/.dts/build/tool-version.d.ts +1 -1
  107. package/dist/.dts/build/usage-report.d.ts +19 -19
  108. package/dist/.dts/build/usage-report.d.ts.map +1 -1
  109. package/dist/.dts/eslint-plugin/index.d.ts +16 -5
  110. package/dist/.dts/eslint-plugin/index.d.ts.map +1 -1
  111. package/dist/.dts/eslint-plugin/no-raw-process-env.d.ts +4 -4
  112. package/dist/.dts/evidence/define-projection.d.ts +15 -16
  113. package/dist/.dts/evidence/define-projection.d.ts.map +1 -1
  114. package/dist/.dts/evidence/index.d.ts +11 -15
  115. package/dist/.dts/evidence/index.d.ts.map +1 -1
  116. package/dist/.dts/helpers/index.d.ts +15 -18
  117. package/dist/.dts/helpers/index.d.ts.map +1 -1
  118. package/dist/.dts/helpers/validators.d.ts +2 -2
  119. package/dist/.dts/helpers/validators.d.ts.map +1 -1
  120. package/dist/.dts/node/index.d.ts +19 -0
  121. package/dist/.dts/node/index.d.ts.map +1 -1
  122. package/dist/.dts/runtime/create.d.ts +3 -3
  123. package/dist/.dts/runtime/document.d.ts +90 -99
  124. package/dist/.dts/runtime/document.d.ts.map +1 -1
  125. package/dist/.dts/runtime/errors.d.ts +5 -5
  126. package/dist/.dts/runtime/reset.d.ts +1 -1
  127. package/dist/.dts/runtime/types.d.ts +23 -24
  128. package/dist/.dts/runtime/types.d.ts.map +1 -1
  129. package/dist/.dts/runtime/validate.d.ts +1 -1
  130. package/dist/.dts7/_ipc/build-fs.d.ts +3 -3
  131. package/dist/.dts7/_ipc/build-fs.d.ts.map +1 -1
  132. package/dist/.dts7/_ipc/display-path.d.ts +1 -1
  133. package/dist/.dts7/_ipc/glob.d.ts +3 -2
  134. package/dist/.dts7/_ipc/glob.d.ts.map +1 -1
  135. package/dist/.dts7/_ipc/no-node-fs.d.ts +2 -2
  136. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts +16 -16
  137. package/dist/.dts7/_ipc/resolve-tsconfig-paths.d.ts.map +1 -1
  138. package/dist/.dts7/_ipc/typescript.d.ts +4 -4
  139. package/dist/.dts7/build/assemble-project.d.ts +14 -15
  140. package/dist/.dts7/build/assemble-project.d.ts.map +1 -1
  141. package/dist/.dts7/build/change-model.d.ts +14 -14
  142. package/dist/.dts7/build/change-model.d.ts.map +1 -1
  143. package/dist/.dts7/build/check-artifacts.d.ts +4 -4
  144. package/dist/.dts7/build/check-artifacts.d.ts.map +1 -1
  145. package/dist/.dts7/build/citation-verification.d.ts +13 -14
  146. package/dist/.dts7/build/citation-verification.d.ts.map +1 -1
  147. package/dist/.dts7/build/compatibility.d.ts +24 -24
  148. package/dist/.dts7/build/compatibility.d.ts.map +1 -1
  149. package/dist/.dts7/build/contract-model.d.ts +10 -10
  150. package/dist/.dts7/build/contract-model.d.ts.map +1 -1
  151. package/dist/.dts7/build/deep-equal.d.ts +2 -2
  152. package/dist/.dts7/build/deep-freeze.d.ts +2 -2
  153. package/dist/.dts7/build/dependency-graph.d.ts +48 -55
  154. package/dist/.dts7/build/dependency-graph.d.ts.map +1 -1
  155. package/dist/.dts7/build/dependency-model.d.ts +18 -18
  156. package/dist/.dts7/build/dependency-model.d.ts.map +1 -1
  157. package/dist/.dts7/build/discover.d.ts +11 -11
  158. package/dist/.dts7/build/discover.d.ts.map +1 -1
  159. package/dist/.dts7/build/docs.d.ts +34 -38
  160. package/dist/.dts7/build/docs.d.ts.map +1 -1
  161. package/dist/.dts7/build/env-example.d.ts +13 -13
  162. package/dist/.dts7/build/env-example.d.ts.map +1 -1
  163. package/dist/.dts7/build/errors.d.ts +8 -8
  164. package/dist/.dts7/build/evidence-cache.d.ts +23 -23
  165. package/dist/.dts7/build/evidence-cache.d.ts.map +1 -1
  166. package/dist/.dts7/build/evidence-model.d.ts +3 -3
  167. package/dist/.dts7/build/evidence-reference.d.ts +15 -15
  168. package/dist/.dts7/build/evidence-reference.d.ts.map +1 -1
  169. package/dist/.dts7/build/evidence-snapshot.d.ts +47 -53
  170. package/dist/.dts7/build/evidence-snapshot.d.ts.map +1 -1
  171. package/dist/.dts7/build/exclusive-group.d.ts +4 -4
  172. package/dist/.dts7/build/exclusive-group.d.ts.map +1 -1
  173. package/dist/.dts7/build/finding-model.d.ts +12 -12
  174. package/dist/.dts7/build/finding-model.d.ts.map +1 -1
  175. package/dist/.dts7/build/generate-documentation.d.ts +19 -19
  176. package/dist/.dts7/build/generate-documentation.d.ts.map +1 -1
  177. package/dist/.dts7/build/generate-env-artifacts.d.ts +43 -43
  178. package/dist/.dts7/build/generate-env-artifacts.d.ts.map +1 -1
  179. package/dist/.dts7/build/generate-evidence.d.ts +19 -19
  180. package/dist/.dts7/build/generate-evidence.d.ts.map +1 -1
  181. package/dist/.dts7/build/generate-manifest.d.ts +11 -12
  182. package/dist/.dts7/build/generate-manifest.d.ts.map +1 -1
  183. package/dist/.dts7/build/generate-usage.d.ts +23 -24
  184. package/dist/.dts7/build/generate-usage.d.ts.map +1 -1
  185. package/dist/.dts7/build/generated-banner.d.ts +5 -5
  186. package/dist/.dts7/build/governance-fields.d.ts +7 -7
  187. package/dist/.dts7/build/humanize-key.d.ts +1 -1
  188. package/dist/.dts7/build/humanize-key.d.ts.map +1 -1
  189. package/dist/.dts7/build/index.d.ts +20 -36
  190. package/dist/.dts7/build/index.d.ts.map +1 -1
  191. package/dist/.dts7/build/lifecycle-model.d.ts +87 -85
  192. package/dist/.dts7/build/lifecycle-model.d.ts.map +1 -1
  193. package/dist/.dts7/build/link.d.ts +38 -39
  194. package/dist/.dts7/build/link.d.ts.map +1 -1
  195. package/dist/.dts7/build/literal-eval.d.ts +2 -2
  196. package/dist/.dts7/build/literal-eval.d.ts.map +1 -1
  197. package/dist/.dts7/build/live-expirations.d.ts +14 -13
  198. package/dist/.dts7/build/live-expirations.d.ts.map +1 -1
  199. package/dist/.dts7/build/manifest.d.ts +6 -6
  200. package/dist/.dts7/build/map-utils.d.ts +4 -4
  201. package/dist/.dts7/build/merge-documentation.d.ts +9 -8
  202. package/dist/.dts7/build/merge-documentation.d.ts.map +1 -1
  203. package/dist/.dts7/build/ownership-model.d.ts +14 -15
  204. package/dist/.dts7/build/ownership-model.d.ts.map +1 -1
  205. package/dist/.dts7/build/parse.d.ts +20 -21
  206. package/dist/.dts7/build/parse.d.ts.map +1 -1
  207. package/dist/.dts7/build/reference-projections.d.ts +36 -38
  208. package/dist/.dts7/build/reference-projections.d.ts.map +1 -1
  209. package/dist/.dts7/build/resolution/resolve-import.d.ts +18 -14
  210. package/dist/.dts7/build/resolution/resolve-import.d.ts.map +1 -1
  211. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts +26 -26
  212. package/dist/.dts7/build/resolution/resolve-package-schema.d.ts.map +1 -1
  213. package/dist/.dts7/build/resolution/resolve-within-root.d.ts +9 -9
  214. package/dist/.dts7/build/sarif.d.ts +5 -5
  215. package/dist/.dts7/build/sarif.d.ts.map +1 -1
  216. package/dist/.dts7/build/scan-dependencies.d.ts +17 -16
  217. package/dist/.dts7/build/scan-dependencies.d.ts.map +1 -1
  218. package/dist/.dts7/build/sort-by-identity.d.ts +1 -1
  219. package/dist/.dts7/build/source-position.d.ts +13 -13
  220. package/dist/.dts7/build/tool-version.d.ts +1 -1
  221. package/dist/.dts7/build/usage-report.d.ts +19 -19
  222. package/dist/.dts7/build/usage-report.d.ts.map +1 -1
  223. package/dist/.dts7/eslint-plugin/index.d.ts +16 -5
  224. package/dist/.dts7/eslint-plugin/index.d.ts.map +1 -1
  225. package/dist/.dts7/eslint-plugin/no-raw-process-env.d.ts +4 -4
  226. package/dist/.dts7/evidence/define-projection.d.ts +15 -16
  227. package/dist/.dts7/evidence/define-projection.d.ts.map +1 -1
  228. package/dist/.dts7/evidence/index.d.ts +11 -15
  229. package/dist/.dts7/evidence/index.d.ts.map +1 -1
  230. package/dist/.dts7/helpers/index.d.ts +15 -18
  231. package/dist/.dts7/helpers/index.d.ts.map +1 -1
  232. package/dist/.dts7/helpers/validators.d.ts +2 -2
  233. package/dist/.dts7/helpers/validators.d.ts.map +1 -1
  234. package/dist/.dts7/node/index.d.ts +19 -0
  235. package/dist/.dts7/node/index.d.ts.map +1 -1
  236. package/dist/.dts7/runtime/create.d.ts +3 -3
  237. package/dist/.dts7/runtime/document.d.ts +90 -99
  238. package/dist/.dts7/runtime/document.d.ts.map +1 -1
  239. package/dist/.dts7/runtime/errors.d.ts +5 -5
  240. package/dist/.dts7/runtime/reset.d.ts +1 -1
  241. package/dist/.dts7/runtime/types.d.ts +23 -24
  242. package/dist/.dts7/runtime/types.d.ts.map +1 -1
  243. package/dist/.dts7/runtime/validate.d.ts +1 -1
  244. package/dist/{build-DNAYWD2B.js → build-UEENZEUX.js} +37 -39
  245. package/dist/build-UEENZEUX.js.map +1 -0
  246. package/dist/build.cjs +36 -38
  247. package/dist/build.cjs.map +1 -1
  248. package/dist/build.js +36 -38
  249. package/dist/build.js.map +1 -1
  250. package/dist/{chunk-HAGMVMN5.js → chunk-TBL3O7IG.js} +2 -2
  251. package/dist/cli/index.js +29 -28
  252. package/dist/cli/index.js.map +1 -1
  253. package/dist/eslint-plugin/index.cjs.map +1 -1
  254. package/dist/eslint-plugin/index.js.map +1 -1
  255. package/dist/evidence.cjs +1 -1
  256. package/dist/evidence.cjs.map +1 -1
  257. package/dist/evidence.js +1 -1
  258. package/dist/evidence.js.map +1 -1
  259. package/dist/helpers.cjs +4 -4
  260. package/dist/helpers.cjs.map +1 -1
  261. package/dist/helpers.js +4 -4
  262. package/dist/helpers.js.map +1 -1
  263. package/dist/index.cjs.map +1 -1
  264. package/dist/index.js.map +1 -1
  265. package/examples/README.md +1 -1
  266. package/package.json +18 -10
  267. package/schemas/contract-model.schema.json +7 -7
  268. package/schemas/env-cap-report.schema.json +88 -88
  269. package/skills/env-cap/SKILL.md +12 -13
  270. package/skills/env-cap/references/api.md +1 -1
  271. package/specs/architecture.md +145 -120
  272. package/specs/generated-artifacts.md +78 -70
  273. package/specs/migrations/README.md +6 -6
  274. package/specs/migrations/from-centralized-schema.md +1 -1
  275. package/specs/migrations/from-t3-env.md +9 -9
  276. package/PROMPT.md +0 -89
  277. package/dist/build-DNAYWD2B.js.map +0 -1
  278. /package/dist/{chunk-HAGMVMN5.js.map → chunk-TBL3O7IG.js.map} +0 -0
@@ -1,40 +1,49 @@
1
1
  # Reading the benchmarks
2
2
 
3
- This guide is for the person **reading** `BENCHMARKS.md`: a platform engineer deciding whether to run
4
- this package, a CTO estimating what it adds to the infrastructure bill, or a maintainer checking a
5
- change. It explains why the benchmarks exist, how to read each number, and, as important, what you
6
- must **not** do with them.
3
+ This guide is for the person **reading** `BENCHMARKS.md`. That reader may be:
4
+
5
+ - a platform engineer deciding whether to run this package;
6
+ - a CTO estimating what it adds to the infrastructure bill;
7
+ - a maintainer checking a change.
8
+
9
+ It explains why the benchmarks exist, how to read each number, and, as important, what you must **not** do
10
+ with them.
7
11
 
8
12
  Its companion, [WRITING-BENCHMARKS.md](WRITING-BENCHMARKS.md), explains how benchmarks are written and
9
13
  documented.
10
14
 
11
15
  ## Why we benchmark
12
16
 
13
- Every dependency has a price. Most of it is invisible until it is large: a few milliseconds added to
14
- every request, a CPU core that is busier than it needs to be, a function that is fast on ten items and
15
- unusable on ten thousand, a cold start that grows with every module. By then it is expensive to
16
- remove.
17
+ Every dependency has a price. Most of it is invisible until it is large:
18
+
19
+ - a few milliseconds added to every request;
20
+ - a CPU core that is busier than it needs to be;
21
+ - a function that is fast on ten items and unusable on ten thousand;
22
+ - a cold start that grows with every module.
23
+
24
+ By then it is expensive to remove.
17
25
 
18
26
  The benchmarks make that price visible **before** you adopt the package and **every time** it changes.
19
- They lean toward costs on purpose. The rest of the repository explains the benefits; this report tells
27
+ They lean toward costs on purpose. The rest of the repository explains the benefits. This report tells
20
28
  you what you are paying for them, in time and in money, and how the bill grows with your workload.
21
29
 
22
30
  ## What is in the report
23
31
 
24
32
  `BENCHMARKS.md` has four parts, in the order a decision-maker needs them:
25
33
 
26
- 1. **What adopting this package costs.** The headline: added latency, CPU and memory per operation at
27
- a typical workload and at the largest tested size, an estimated compute cost per million
28
- operations, and the code size every process must load. If you read nothing else, read this.
34
+ 1. **What adopting this package costs.** The headline. It shows the added latency, CPU and memory per
35
+ operation, at a typical workload and at the largest tested size. It also shows an estimated compute
36
+ cost per million operations, and the code size every process must load. If you read nothing else, read
37
+ this.
29
38
  2. **End-to-end.** The same operation done with no package and through the package, using empty or
30
- minimal functions on both sides, at every size of the ladder (ten doubling sizes by default; the
31
- report's environment section lists the sizes actually used). The difference is the package's total impact, with
32
- nothing of your own application mixed in.
33
- 3. **Function by function.** Every function measured alone across the same sizes, with: why it is
34
- benchmarked, what poor performance would mean, its documented big-O and the reason for it, every
35
- variable that could change its cost, and what was deliberately not covered.
39
+ minimal functions on both sides. It is measured at every size of the ladder: ten doubling sizes by
40
+ default, and the report's environment section lists the sizes actually used. The difference is the
41
+ package's total impact, with nothing of your own application mixed in.
42
+ 3. **Function by function.** Every function measured alone across the same sizes. Each comes with why it
43
+ is benchmarked, what poor performance would mean, and its documented big-O with the reason for it. It
44
+ also lists every variable that could change its cost, and what was deliberately not covered.
36
45
  4. **What makes up one operation.** Each function's cost, multiplied by how often one operation calls
37
- it, with nested calls counted once, as a share of the whole operation -- where the cost actually
46
+ it, as a share of the whole operation. Nested calls are counted once. This is where the cost actually
38
47
  lives.
39
48
 
40
49
  ## How to read a table
@@ -51,12 +60,12 @@ you what you are paying for them, in time and in money, and how the bill grows w
51
60
 
52
61
  ## Big-O and the growth exponent
53
62
 
54
- Big-O describes how cost grows as size grows -- more useful than any single timing, because it tells
55
- you what happens at a size you did not test. The report fits a line through the log of time against
56
- the log of size across the **largest** sizes (the top five of a long ladder: a real cost is a fixed
57
- per-call overhead plus work that grows, and the overhead hides the growth at small sizes); the slope
58
- is the **growth exponent**, snapped to the nearest class. The fit's R² is reported next to it, and when
59
- the cost moves but does not follow a power law (a step, a cache cliff) no class is claimed at all:
63
+ Big-O describes how cost grows as size grows. That is more useful than any single timing, because it tells
64
+ you what happens at a size you did not test. The report fits a line through the log of time against the
65
+ log of size across the **largest** sizes. On a long ladder that is the top five. A real cost is a fixed
66
+ per-call overhead plus work that grows, and the overhead hides the growth at small sizes. The slope is the
67
+ **growth exponent**, snapped to the nearest class. The fit's R² is reported next to it. When the cost
68
+ moves but does not follow a power law (a step, a cache cliff), no class is claimed at all. The classes:
60
69
 
61
70
  | Exponent (about) | Class | What doubling the size does to the time |
62
71
  | ---------------- | -------------- | --------------------------------------- |
@@ -69,19 +78,19 @@ the cost moves but does not follow a power law (a step, a cache cliff) no class
69
78
 
70
79
  Each function shows its **documented** class next to its **measured** class with an agreement label:
71
80
 
72
- - ✅ **matches** -- the code behaves as documented.
73
- - 🟡 **close** -- neighbouring classes. Constant vs logarithmic and linear vs linearithmic cannot be
81
+ - ✅ **matches**: the code behaves as documented.
82
+ - 🟡 **close**: neighbouring classes. Constant vs logarithmic and linear vs linearithmic cannot be
74
83
  reliably separated on a bounded ladder; treat it as a match unless the exponent has moved.
75
- - ⚠️ **differs** -- two or more classes apart. Either the documentation or the code is wrong. This is
84
+ - ⚠️ **differs**: two or more classes apart. Either the documentation or the code is wrong. This is
76
85
  the most useful line in the report.
77
- - ❔ **not enough data** -- fewer than two usable sizes; something failed.
86
+ - ❔ **not enough data**: fewer than two usable sizes; something failed.
78
87
 
79
88
  ## The dollar figures
80
89
 
81
90
  Time becomes money through two bracketing price shapes, because platforms bill differently:
82
91
 
83
- - **Low:** CPU-priced compute (a container or VM billed per vCPU-hour) -- you pay for CPU seconds.
84
- - **High:** duration-and-memory-priced functions (billed per GB-second) -- you pay for wall seconds
92
+ - **Low:** CPU-priced compute (a container or VM billed per vCPU-hour): you pay for CPU seconds.
93
+ - **High:** duration-and-memory-priced functions (billed per GB-second): you pay for wall seconds
85
94
  times the memory the platform reserves, never less than its minimum.
86
95
 
87
96
  The rates are rounded published list prices and are **assumptions**; they drift with time and region.
@@ -91,8 +100,8 @@ Treat the result as an order-of-magnitude comparison ("fractions of a cent per m
91
100
 
92
101
  ## Results are not comparable between runs
93
102
 
94
- This is the rule that matters most. **A benchmark number is a measurement of one run on one machine at
95
- one moment.** It is not a property of the package.
103
+ This is the rule that matters most: **a benchmark number is a measurement of one run on one machine at one
104
+ moment**. It is not a property of the package.
96
105
 
97
106
  - Do **not** compare numbers from different machines, operating systems, Node versions, or runners. A
98
107
  laptop and a CI runner differ by large factors in both directions.
@@ -106,15 +115,15 @@ one moment.** It is not a property of the package.
106
115
 
107
116
  What the numbers **are** good for:
108
117
 
109
- - **Change over time on comparable hardware.** The same suite on the same kind of machine before and
118
+ - **Change over time on comparable hardware**. The same suite on the same kind of machine before and
110
119
  after a change shows whether the change made the package slower. Look for movement larger than the
111
120
  run-to-run noise.
112
- - **Shape, not only level.** A change in growth class (O(n) becoming O(n²)) is a much bigger signal
113
- than a 15% shift in a timing, and it is far less sensitive to the machine than a time is, because it
121
+ - **Shape, not only level**. A change in growth class (O(n) becoming O(n²)) is a much bigger signal
122
+ than a 15% shift in a timing. It is also far less sensitive to the machine than a time is, because it
114
123
  is a ratio between sizes on the same run. It still assumes the same sizes, workload and runtime.
115
- - **Relative cost between functions.** Which function dominates the overhead is usually the same on
124
+ - **Relative cost between functions**. Which function dominates the overhead is usually the same on
116
125
  any machine, even when the absolute times are not.
117
- - **Order of magnitude.** Microseconds, milliseconds or seconds per operation: that distinction is
126
+ - **Order of magnitude**. Microseconds, milliseconds or seconds per operation: that distinction is
118
127
  stable enough to plan with.
119
128
 
120
129
  ## What the numbers do not prove
@@ -126,11 +135,11 @@ What the numbers **are** good for:
126
135
  power law. A high R² does not show the class is right, and a low one means no class is reported.
127
136
  - **The overhead is a difference.** `end-to-end:overhead` is not measured; it is the with-package
128
137
  time minus the baseline time at each size, never below zero. A difference of two noisy medians is
129
- noisier than either, so the history page shows it for reading only and gives it no complexity class,
130
- and the pull-request summary does not report a class shift for it. Read the baseline and with-package
131
- groups, and the "What the package adds" table, instead.
138
+ noisier than either. The history page therefore shows it for reading only and gives it no complexity
139
+ class. The pull-request summary does not report a class shift for it. Read the baseline and
140
+ with-package groups, and the "What the package adds" table, instead.
132
141
  - **A relative cost is still a measurement.** Dividing by the baseline removes much of the machine,
133
- not all of it: compilation, garbage collection and contention on the runner still move it. Below the
142
+ not all of it. Compilation, garbage collection and contention on the runner still move it. Below the
134
143
  timer-noise floor the percentage is not shown.
135
144
  - **One run per commit is not a repeat.** The history holds one measurement for each recorded commit.
136
145
  A trend is more convincing than a point; a single point moving is ordinary noise.
@@ -138,66 +147,73 @@ What the numbers **are** good for:
138
147
  ## Noise
139
148
 
140
149
  Even on a quiet machine, repeated runs differ. Very fast operations (microseconds and below) are the
141
- noisiest in relative terms; the engine batches them and reports the per-operation value, but a 30-40%
150
+ noisiest in relative terms. The engine batches them and reports the per-operation value, but a 30-40%
142
151
  swing between runs on those is ordinary. Slow operations are steadier. Read the median and p95
143
152
  together, and trust a trend over a single run. The pull-request summary shows the change against the last
144
- run, but never judges it: a raw comparison is between two runs on different machines. What can fail a pull request is limited to growth classes and
145
- baseline-relative ratios, which are far less sensitive to the machine than a raw time: see "History, pull
146
- requests and the history page".
153
+ run, but never judges it: a raw comparison is between two runs on different machines. What can fail a pull
154
+ request is limited to growth classes and baseline-relative ratios. Those are far less sensitive to the
155
+ machine than a raw time (see "History, pull requests and the history page").
147
156
 
148
157
  ## How the documentation is done
149
158
 
150
159
  Documentation is part of the benchmark definition, not an afterthought, and the suite will not load
151
160
  without it. For every function the report prints, in this order:
152
161
 
153
- 1. **Why we benchmark it** -- where it runs, how often, and who feels it.
154
- 2. **What poor performance would mean** -- the consequence in latency, capacity and spend.
155
- 3. **Expected growth** -- the big-O and the mechanism that causes it.
156
- 4. **Variables that could change its cost** -- each one swept, measured as a variant, or fixed at a
162
+ 1. **Why we benchmark it**: where it runs, how often, and who feels it.
163
+ 2. **What poor performance would mean**: the consequence in latency, capacity and spend.
164
+ 3. **Expected growth**: the big-O and the mechanism that causes it.
165
+ 4. **Variables that could change its cost**: each one swept, measured as a variant, or fixed at a
157
166
  stated value.
158
- 5. **Deliberately not covered** -- the honest gaps, with reasons.
159
- 6. **The measurements** -- every size, median, p95, CPU, memory, throughput, and the measured class next
167
+ 5. **Deliberately not covered**: the honest gaps, with reasons.
168
+ 6. **The measurements**: every size, median, p95, CPU, memory, throughput, and the measured class next
160
169
  to the documented one.
161
170
 
162
171
  If a section reads as vague, that is a documentation bug: open an issue or fix it.
163
172
 
164
173
  ## History, pull requests and the history page
165
174
 
166
- When a pull request touches benchmarked code, CI re-runs the suite and posts a summary: the end-to-end
167
- change first, then any function whose growth class shifted, then ordinary timing movements beyond
168
- their thresholds. Three gates can fail the run. None of them compares a raw time with another run's, because
169
- two runs are on different machines. Two compare growth classes, which describe the shape of the curve and
170
- not the speed of the machine: the measured class against the documented big-O (a function whose class
171
- **differs** fails), and against the class at the last release (a function whose class has gotten **worse**
172
- fails, unless `.repo-contract/exceptions/benchmark-complexity.json` records a person's acceptance of it).
175
+ When a pull request touches benchmarked code, CI re-runs the suite and posts a summary. The summary shows
176
+ the end-to-end change first, then any function whose growth class shifted, then ordinary timing movements
177
+ beyond their thresholds. Three gates can fail the run. None of them compares a raw time with another run's,
178
+ because two runs are on different machines.
179
+
180
+ Two compare the measured growth class, which describes the shape of the curve and not the speed of the
181
+ machine:
182
+
183
+ - against the documented big-O: a function whose class **differs** fails;
184
+ - against the class at the last release: a function whose class got **worse** fails, unless
185
+ `.repo-contract/exceptions/benchmark-complexity.json` records a person's acceptance of it.
186
+
173
187
  The third is a ratio: the package's overhead _relative to its own baseline_, measured in the same run,
174
- growing past an allowance (50% for millisecond-scale work, 70% for microsecond-scale work, which is
175
- noisier). The baseline and the package are sampled interleaved, so the overhead is a per-pair
176
- difference with a 95% confidence interval; a growth that sits inside the intervals of the two runs
177
- compared is reported as a note, never a failure. What the gate judges is main measured on the same
178
- runner in the same job; the committed results of main and of the last release are judged only when
179
- they came from the same CPU model, since for fast work the ratio also depends on how much of a bare
180
- baseline is process start-up. A function whose big-O could not be
181
- determined (too few sizes, or no difference between them) is a **warning**: nothing is known to be wrong, but
182
- nothing is checked. Raw time against another run is shown, never judged. A failed gate fails the benchmark
183
- job; whether a red job blocks the merge is decided by the repository's ruleset, not by the gate.
184
-
185
- After a merge, a job measures the merge commit and records it -- the results file and a history entry
186
- naming the commit, pull request and version -- through its own small pull request. Each entry also keeps
187
- how noisy that run was (standard deviation, p95 and iteration count for every size) and the processor it
188
- ran on, so a reader can judge later whether a change is larger than the run's own spread. A generated
189
- history page opens with why the benchmarks exist and what they do and do not show, then charts every
190
- function across runs, with every figure also available as a table, and shows the baseline, the
191
- with-package time and the difference side by side.
188
+ growing past an allowance. The allowance is 50% for millisecond-scale work and 70% for microsecond-scale
189
+ work, which is noisier. The baseline and the package are sampled interleaved, so the overhead is a
190
+ per-pair difference with a 95% confidence interval. A growth that sits inside the intervals of the two runs
191
+ compared is reported as a note, never a failure. What the gate judges is main measured on the same runner
192
+ in the same job. The committed results of main and of the last release are judged only when they came from
193
+ the same CPU model. The reason: for fast work, the ratio also depends on how much of a bare baseline is
194
+ process start-up.
195
+
196
+ A function whose big-O could not be determined (too few sizes, or no difference between them) is a
197
+ **warning**. Nothing is known to be wrong, but nothing is checked. Raw time against another run is shown,
198
+ never judged. A failed gate fails the benchmark job; whether a red job blocks the merge is decided by the
199
+ repository's ruleset, not by the gate.
200
+
201
+ After a merge, a job measures the merge commit and records it through its own small pull request. The
202
+ record is the results file and a history entry naming the commit, pull request and version. Each entry
203
+ also keeps how noisy that run was (standard deviation, p95 and iteration count for every size) and the
204
+ processor it ran on. A reader can then judge later whether a change is larger than the run's own spread. A
205
+ generated history page opens with why the benchmarks exist and what they do and do not show. It then
206
+ charts every function across runs, with every figure also available as a table. It shows the baseline,
207
+ the with-package time and the difference side by side.
192
208
 
193
209
  ## Glossary
194
210
 
195
- - **Operation** -- one unit of the work the package performs, as defined by the suite.
196
- - **Size / `n`** -- how much that operation processes (records, calls, files).
197
- - **Baseline** -- the same operation with no package, using an empty or minimal function.
198
- - **Overhead / added** -- with-package time minus baseline time: the package's own cost. Derived from the
211
+ - **Operation**: one unit of the work the package performs, as defined by the suite.
212
+ - **Size / `n`**: how much that operation processes (records, calls, files).
213
+ - **Baseline**: the same operation with no package, using an empty or minimal function.
214
+ - **Overhead / added**: the package's own cost, with-package time minus baseline time. Derived from the
199
215
  two measured groups, never below zero, and not itself classified.
200
- - **Median / p95** -- the middle sample, and the value 95% of samples beat.
201
- - **Heap Δ** -- memory the operation left allocated.
202
- - **Batch** -- the number of back-to-back repetitions inside one sample for very fast operations.
203
- - **Cold start** -- the cost of loading and initializing the package in a fresh process.
216
+ - **Median / p95**: the middle sample, and the value 95% of samples beat.
217
+ - **Heap Δ**: memory the operation left allocated.
218
+ - **Batch**: the number of back-to-back repetitions inside one sample for very fast operations.
219
+ - **Cold start**: the cost of loading and initializing the package in a fresh process.
@@ -1,10 +1,13 @@
1
1
  # Benchmarks
2
2
 
3
- This folder is the performance and cost record of the package: what adopting it costs in time and
4
- money, how each function scales, and where the cost comes from. It is built entirely by
5
- [`internal-package-contract`](https://github.com/MaverickCER/internal-package-contract): the package
6
- supplies **what to run** (an input), the contract **stresses it through ten sizes, measures it, checks
7
- the big-O and prices it**, and writes a **report** and a machine-readable **result** (the output).
3
+ This folder is the performance and cost record of the package. It shows what adopting it costs in
4
+ time and money, how each function scales, and where the cost comes from. It is built entirely by
5
+ [`internal-package-contract`](https://github.com/MaverickCER/internal-package-contract):
6
+
7
+ - the package supplies **what to run** (an input);
8
+ - the contract **stresses it through ten sizes, measures it, checks the big-O and prices it**;
9
+ - the contract writes a **report** and a machine-readable **result** (the output).
10
+
8
11
  Nothing in this folder implements timing, statistics or reporting.
9
12
 
10
13
  ## Read first
@@ -96,8 +99,8 @@ export default defineSuite({
96
99
  | `inEndToEnd` | no | How often one end-to-end operation calls the function, for the attribution section. |
97
100
 
98
101
  `expectedComplexity` is one of `constant`, `logarithmic`, `linear`, `linearithmic`, `quadratic`,
99
- `exponential-or-worse`. Return a value that depends on the work (the contract keeps it alive so
100
- nothing is optimized away); return `timed(ms)` only when an operation is timed elsewhere, such as a
102
+ `exponential-or-worse`. Return a value that depends on the work; the contract keeps it alive so
103
+ nothing is optimized away. Return `timed(ms)` only when an operation is timed elsewhere, such as a
101
104
  child process.
102
105
 
103
106
  ## The output: `results.json`
@@ -121,6 +124,6 @@ analysis complexity measured class, exponent and notation per group, with
121
124
  cost the typical and largest sizes used for the headline numbers
122
125
  ```
123
126
 
124
- Because results are not comparable between machines or runs, history and pull-request summaries look at
125
- **change over time on comparable hardware** and at **changes in growth class**, never at one absolute
127
+ Results are not comparable between machines or runs. History and pull-request summaries therefore look
128
+ at **change over time on comparable hardware** and at **changes in growth class**, never at one absolute
126
129
  number. See [READING-BENCHMARKS.md](READING-BENCHMARKS.md).
@@ -1,26 +1,28 @@
1
1
  # Writing benchmarks
2
2
 
3
3
  This guide is for the person adding or changing a benchmark. It explains **what** to test, **how** to
4
- test it, **why** each choice is made, and **how to document** the result so a platform engineer or CTO
5
- can read it without knowing the code. Its companion, [READING-BENCHMARKS.md](READING-BENCHMARKS.md),
6
- explains how to interpret what you produce.
4
+ test it, **why** each choice is made, and **how to document** the result. The goal is a result a platform
5
+ engineer or CTO can read without knowing the code. Its companion,
6
+ [READING-BENCHMARKS.md](READING-BENCHMARKS.md), explains how to interpret what you produce.
7
7
 
8
8
  The benchmarks exist to answer one question for the people who run this package in production:
9
- **what does it cost me, in time and in money, and how does that grow as my workload grows?** The rest
10
- of the repository makes the case for what the package gives you; the benchmarks are deliberately
9
+
10
+ **What does it cost me, in time and in money, and how does that grow as my workload grows?**
11
+
12
+ The rest of the repository makes the case for what the package gives you. The benchmarks are deliberately
11
13
  honest about what it costs.
12
14
 
13
15
  ## The three views
14
16
 
15
17
  Every suite measures the package from three angles, each building on the last.
16
18
 
17
- 1. **End-to-end: the total impact.** One operation done two ways, with empty or minimal functions
18
- plugged in: once with no package (the _baseline_) and once routed through the package. The
19
- difference is the package's own cost -- the floor it imposes on every operation. Keep both sides
20
- trivial on purpose: if you plug in real work, you are measuring that work.
21
- 2. **Functions: each part on its own.** Every function the end-to-end run uses (and every public
22
- function worth knowing about) is measured separately across the full size ladder, so we can see
23
- how each one scales and whether it behaves the way we say it does.
19
+ 1. **End-to-end: the total impact.** One operation is done two ways, with empty or minimal functions plugged
20
+ in. It runs once with no package (the _baseline_) and once routed through the package. The difference is
21
+ the package's own cost: the floor it imposes on every operation. Keep both sides trivial on purpose: if
22
+ you plug in real work, you are measuring that work.
23
+ 2. **Functions: each part on its own.** Every function the end-to-end run uses is measured separately across
24
+ the full size ladder. So is every public function worth knowing about. That shows how each one scales and
25
+ whether it behaves the way we say it does.
24
26
  3. **Contribution: where the cost lives.** Each function says how often one end-to-end operation calls
25
27
  it (`inEndToEnd`). The report multiplies that by the function's measured cost and shows its share
26
28
  of the overhead, so effort goes to the function that actually matters.
@@ -38,20 +40,20 @@ a function whose cost nobody can see.
38
40
  serverless invocation that scales from zero.
39
41
  - **Memory**, as well as time: what the operation allocates and retains. The report records the heap
40
42
  delta of every sample.
41
- - **Every variable that could change the cost.** This is the part that is easy to skip and the part
42
- that matters most. Walk through each of these for every function and decide, explicitly, whether it
43
- is _swept_ (the size axis), a _variant_ (measured separately), or _fixed_ (held constant on
44
- purpose, with the value stated):
45
- - **Input size** -- the size ladder below. Always swept.
46
- - **Input shape** -- flat vs deeply nested, many small items vs few large ones, wide vs narrow
47
- objects, strings vs numbers, sorted vs random vs adversarial order.
48
- - **State** -- empty vs populated, first call (cold) vs repeated call (warm), cache hit vs miss.
49
- - **Options and modes** -- every flag that changes the algorithm used.
50
- - **Outcome** -- the success path **and** the error path. Errors are often slower and often hit
43
+ - **Every variable that could change the cost.** This is the part that is tempting to skip and the part
44
+ that matters most. Walk through each of these for every function and decide, explicitly, how it is
45
+ treated. Each is _swept_ (the size axis), a _variant_ (measured separately), or _fixed_ (held constant
46
+ on purpose, with the value stated):
47
+ - **Input size**: the size ladder below. Always swept.
48
+ - **Input shape**: flat vs deeply nested, many small items vs few large ones, wide vs narrow objects.
49
+ Also strings vs numbers, and sorted vs random vs adversarial order.
50
+ - **State**: empty vs populated, first call (cold) vs repeated call (warm), cache hit vs miss.
51
+ - **Options and modes**: every flag that changes the algorithm used.
52
+ - **Outcome**: the success path **and** the error path. Errors are often slower and often hit
51
53
  under load, exactly when slowness hurts most.
52
- - **Concurrency** -- one caller vs many at once, if the function keeps shared state or does async
54
+ - **Concurrency**: one caller vs many at once, if the function keeps shared state or does async
53
55
  work.
54
- - **Environment** -- runtime and version, platform, available CPU and memory.
56
+ - **Environment**: runtime and version, platform, available CPU and memory.
55
57
  - **What you deliberately do not cover**, listed in `notCovered` with the reason. An honest gap is
56
58
  documentation; a silent gap is a trap.
57
59
 
@@ -63,14 +65,14 @@ Every function is measured at **20, 40, 80, 160, 320, 640, 1280, 2560, 5120 and
63
65
  The default ladder of ten doubling points is not arbitrary. Big-O is estimated by fitting a line through
64
66
  `log(time)` against `log(size)`; its slope is the growth exponent. Three points cannot tell `O(n)`
65
67
  from `O(n log n)` or `O(1)` from `O(log n)`. A ladder spanning more than two orders of magnitude, with
66
- ten points, can. `typicalN` (default 640) marks the size the cost summary quotes -- choose the size a
67
- real operation of this package typically handles, and say why in `workload.description`.
68
+ ten points, can. `typicalN` (default 640) marks the size the cost summary quotes. Choose the size a real
69
+ operation of this package typically handles, and say why in `workload.description`.
68
70
 
69
- Never shorten the ladder for committed results, with one recorded exception: a function too slow to
71
+ Never shorten the ladder for committed results, with one recorded exception. A function too slow to
70
72
  measure at the largest sizes (it compiles a package, or spawns a process, per unit) may list its own
71
- `tiers` -- at least four ascending sizes -- together with a `tiersReason` saying why, which the report
72
- prints beside its results. `--quick` exists for a smoke test and says so in its output; do not commit
73
- what it produces.
73
+ `tiers`. These are at least four ascending sizes, given together with a `tiersReason` saying why, which
74
+ the report prints beside its results. `--quick` exists for a smoke test and says so in its output; do not
75
+ commit what it produces.
74
76
 
75
77
  ## How to test
76
78
 
@@ -80,52 +82,52 @@ what it produces.
80
82
  whose result is thrown away can be optimized into nothing, and you will have benchmarked an empty
81
83
  loop.
82
84
  - **Fresh state when the work changes its own input.** If `run` mutates what `setup` built (committing
83
- to a store, draining a queue), set `fresh: true` so each sample gets a new `setup`. Otherwise the
85
+ to a store, draining a queue), set `fresh: true`. Each sample then gets a new `setup`. Otherwise the
84
86
  second sample measures a different, usually easier, problem.
85
87
  - **Deterministic input.** No `Math.random()`, no `Date.now()` in input generation. Generate from the
86
88
  index (`item i = { id: i, name: "item-" + i }`) so two runs measure the same thing. If you need
87
89
  pseudo-randomness, use a seeded generator and record the seed in the suite.
88
90
  - **No real I/O.** A network call or disk read measures the network or the disk. Simulate it with a
89
- function that resolves from a prepared pool; keep the real code path (queues, deduplication, error
91
+ function that resolves from a prepared pool. Keep the real code path (queues, deduplication, error
90
92
  handling) intact, because that is what the package contributes.
91
93
  - **Import the package the way a consumer does.** Its built entry point, never a source path. The
92
94
  published `exports` map is part of the cost (and of the risk). A package whose costly code is internal
93
- (an engine no entry point exposes on its own) may import that source instead, and its benchmarks
94
- README says so and why.
95
- - **Let the engine handle fast operations.** Operations faster than about a millisecond are repeated
96
- back to back inside one sample and the result divided, because timers cannot resolve them. You
97
- do nothing; the report records the batch size.
95
+ (an engine no entry point exposes on its own) may import that source instead. Its benchmarks README then
96
+ says so and why.
97
+ - **Let the engine handle fast operations.** Timers cannot resolve operations faster than about a
98
+ millisecond. Those are repeated back to back inside one sample, and the result is divided. You do
99
+ nothing; the report records the batch size.
98
100
  - **Quiet machine.** Close heavy programs, plug in a laptop, and run on the same machine you compared
99
101
  against last time. Never compare across machines (see the reading guide).
100
102
 
101
103
  ## How to document a benchmark
102
104
 
103
- `defineSuite` refuses a suite with missing or placeholder documentation, and `npm run benchmark:check`
104
- runs that validation without measuring anything, so it can run in CI on every change. Every function
105
- needs the following, written for a reader who does not know the code.
105
+ `defineSuite` refuses a suite with missing or placeholder documentation. `npm run benchmark:check` runs
106
+ that validation without measuring anything, so it can run in CI on every change. Every function needs the
107
+ following, written for a reader who does not know the code.
106
108
 
107
- ### `why` -- why we benchmark it
109
+ ### `why`: why we benchmark it
108
110
 
109
111
  The reason this function earns a benchmark: where it runs, how often, and who feels it. Not what it
110
- does -- why its cost matters.
112
+ does, but why its cost matters.
111
113
 
112
- > **Good:** "Runs once per getter call, on every request that reads fetched data, so its per-call cost
113
- > is multiplied by the application's whole read traffic."
114
+ > **Good:** "Runs once per getter call, on every request that reads fetched data. Its per-call cost
115
+ > is therefore multiplied by the application's whole read traffic."
114
116
  >
115
117
  > **Bad:** "Tests the commit function."
116
118
 
117
- ### `poorPerformanceMeans` -- what slow would mean
119
+ ### `poorPerformanceMeans`: what slow would mean
118
120
 
119
121
  Translate slowness into consequences for the people running the system: latency users notice, server
120
122
  capacity, cloud spend, cold-start time, memory pressure.
121
123
 
122
- > **Good:** "A slowdown adds directly to every response time and to compute cost per request; at
124
+ > **Good:** "A slowdown adds directly to every response time and to compute cost per request. At
123
125
  > 10,000 items a quadratic regression would turn a 50 ms commit into several seconds and exhaust
124
126
  > request timeouts."
125
127
  >
126
128
  > **Bad:** "Performance would be worse."
127
129
 
128
- ### `expectedComplexity` and `complexityReason` -- the big-O and why
130
+ ### `expectedComplexity` and `complexityReason`: the big-O and why
129
131
 
130
132
  Pick the class you **expect from reading the code** before you run anything:
131
133
 
@@ -139,27 +141,27 @@ Pick the class you **expect from reading the code** before you run anything:
139
141
  | `cubic-or-worse` | O(n³) or worse | Anything faster-growing than quadratic. |
140
142
 
141
143
  The reason is one or two sentences that **name the mechanism**, so a reader can check it against the
142
- code: "walks every newly arrived item once to freeze it" is a reason; "it is linear" is not. After the
143
- run, the report compares the measured class with this one. **Agreement** is the goal; a **difference**
144
- means the documentation or the code is wrong -- both are worth fixing. Neighbouring classes
145
- (constant/logarithmic, linear/linearithmic) are reported as "close" because a bounded ladder cannot
146
- reliably separate them.
144
+ code. For example, "walks every newly arrived item once to freeze it" is a reason; "it is linear" is not.
145
+ After the run, the report compares the measured class with this one. **Agreement** is the goal. A
146
+ **difference** means the documentation or the code is wrong, and both are worth fixing. Neighbouring
147
+ classes (constant/logarithmic, linear/linearithmic) are reported as "close" because a bounded ladder
148
+ cannot reliably separate them.
147
149
 
148
- ### `variables` -- everything that could change the cost
150
+ ### `variables`: everything that could change the cost
149
151
 
150
152
  One row per variable from the checklist above, each marked:
151
153
 
152
- - `swept` -- it is the size axis.
153
- - `variant` -- measured separately; describe each in `variants`.
154
- - `fixed` -- held constant on purpose; give the `value`, so a reader knows what was and was not
154
+ - `swept`: it is the size axis.
155
+ - `variant`: measured separately; describe each in `variants`.
156
+ - `fixed`: held constant on purpose; give the `value`, so a reader knows what was and was not
155
157
  covered.
156
158
 
157
- ### `covers` and `notBenchmarked` -- every input of every public function
159
+ ### `covers` and `notBenchmarked`: every input of every public function
158
160
 
159
161
  A public function with more than one input (several parameters, or an object with several keys) has
160
- several things that can change its cost, and the `BenchmarkCoverage` check fails until each one is
161
- accounted for. In the benchmark that exercises the function, list what you did with every parameter, and
162
- with every key of an object parameter:
162
+ several things that can change its cost. The `BenchmarkCoverage` check fails until each one is accounted
163
+ for. In the benchmark that exercises the function, list what you did with every parameter, and with every
164
+ key of an object parameter:
163
165
 
164
166
  ```js
165
167
  covers: {
@@ -172,17 +174,23 @@ covers: {
172
174
  },
173
175
  ```
174
176
 
175
- Each is one of `swept` (the suite's unit varies it), `sweep:<variable>` (one of the function's `sweeps`),
176
- `variant:<name>` (one of its `variants`), `fixed: <why>` (held at one value, and why) or `not covered: <why>`
177
- (left out, and why). A function that has no benchmark at all is listed in the suite's `notBenchmarked` with
178
- the reason, for example because a benchmarked function that calls it already accounts for its cost.
177
+ Each is one of:
178
+
179
+ - `swept`: the suite's unit varies it;
180
+ - `sweep:<variable>`: one of the function's `sweeps`;
181
+ - `variant:<name>`: one of its `variants`;
182
+ - `fixed: <why>`: held at one value, and why;
183
+ - `not covered: <why>`: left out, and why.
184
+
185
+ A function that has no benchmark at all is listed in the suite's `notBenchmarked` with the reason. One
186
+ such reason: a benchmarked function that calls it already accounts for its cost.
179
187
 
180
- ### `sweeps` -- a second variable that scales
188
+ ### `sweeps`: a second variable that scales
181
189
 
182
190
  Some functions grow with more than one input: the number of records _and_ how many fields each record
183
191
  has. One big-O for both would be wrong, because the two do not have to grow at the same rate. List each
184
- other variable that scales under `sweeps` and the suite measures it on its own, with every other variable
185
- held at its `baseValue` (the suite's own unit is held at `primaryValue`, by default the typical size):
192
+ other variable that scales under `sweeps`, and the suite measures it on its own. Every other variable is
193
+ held at its `baseValue`; the suite's own unit is held at `primaryValue`, by default the typical size:
186
194
 
187
195
  ```js
188
196
  sweeps: [
@@ -197,28 +205,30 @@ sweeps: [
197
205
  ```
198
206
 
199
207
  The variable must also be listed under `variables` as `swept`. `setup` (or `input`) receives a third
200
- argument, `{ variable, values }`: the variable being swept and the value of every variable at this
201
- measurement, so one function builds its input for any of them. In a sweep of another variable, `n` is that variable's value, not the size of the unit: always read every variable from `context.values`, which is right for the primary sweep too. Each sweep is its own group
202
- (`fn:<id>#<variable>`), with its own growth class, its own documented big-O, and its own row in the
203
- report, the history and the pull-request summary.
208
+ argument, `{ variable, values }`. It holds the variable being swept and the value of every variable at
209
+ this measurement, so one function builds its input for any of them. In a sweep of another variable, `n` is
210
+ that variable's value, not the size of the unit. Always read every variable from `context.values`, which
211
+ is right for the primary sweep too. Each sweep is its own group (`fn:<id>#<variable>`), with its own
212
+ growth class and its own documented big-O. It also has its own row in the report, the history and the
213
+ pull-request summary.
204
214
 
205
- ### `variants` -- measured alternatives
215
+ ### `variants`: measured alternatives
206
216
 
207
- When a variable changes the algorithm (cache hit vs miss, flat vs nested, success vs error), measure
208
- each as a named variant across the whole ladder. Each variant is its own row in the report and its own
209
- chart in history, so a regression in one path cannot hide behind another.
217
+ Some variables change the algorithm: cache hit vs miss, flat vs nested, success vs error. Measure each
218
+ alternative as a named variant across the whole ladder. Each variant is its own row in the report and its
219
+ own chart in history, so a regression in one path cannot hide behind another.
210
220
 
211
- ### `notCovered` -- the honest gaps
221
+ ### `notCovered`: the honest gaps
212
222
 
213
223
  Name what you chose not to measure and why ("concurrent callers: the function is synchronous and
214
224
  keeps no shared state"). A reader should never wonder whether something was forgotten.
215
225
 
216
- ### `inEndToEnd` -- where it fits in the whole
226
+ ### `inEndToEnd`: where it fits in the whole
217
227
 
218
228
  State how often one end-to-end operation calls this function (`callsPerOperation`, a number or a
219
229
  function of `n`) and describe the call. This is what lets section 3 of the report attribute the
220
- time of one operation to the functions that cause it. A function measured alone includes everything
221
- it calls: when one attributed function calls another, list the callee's id in `includes` so its time is
230
+ time of one operation to the functions that cause it. A function measured alone includes everything it
231
+ calls. When one attributed function calls another, list the callee's id in `includes`. Its time is then
222
232
  subtracted from the caller and counted once.
223
233
 
224
234
  ### The end-to-end block