@maverickcer/env-cap 0.7.5 → 0.7.7

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 (279) hide show
  1. package/ADOPTION.md +12 -12
  2. package/AGENTS.md +85 -120
  3. package/CHANGELOG.md +36 -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-33O5SDTC.js} +37 -39
  245. package/dist/build-33O5SDTC.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-4D67AQFY.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 +20 -13
  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/decisions/0049-typescript-7-scanner-uses-a-bundled-typescript-6.md +9 -0
  273. package/specs/generated-artifacts.md +78 -70
  274. package/specs/migrations/README.md +6 -6
  275. package/specs/migrations/from-centralized-schema.md +1 -1
  276. package/specs/migrations/from-t3-env.md +9 -9
  277. package/PROMPT.md +0 -89
  278. package/dist/build-DNAYWD2B.js.map +0 -1
  279. /package/dist/{chunk-HAGMVMN5.js.map → chunk-4D67AQFY.js.map} +0 -0
@@ -1,12 +1,12 @@
1
1
  # env-cap: performance and cost report
2
2
 
3
- What does adopting this package add to latency, CPU, memory and compute spend -- and how does that grow with workload? Three views, from the whole to the part: **(1)** the end-to-end total, **(2)** every function on its own, **(3)** which functions make up the total. New to benchmarks? Read [READING-BENCHMARKS.md](../READING-BENCHMARKS.md) first.
3
+ What does adopting this package add to latency, CPU, memory and compute spend, and how does that grow with workload? Three views, from the whole to the part: **(1)** the end-to-end total, **(2)** every function on its own, **(3)** which functions make up the total. New to benchmarks? Read [READING-BENCHMARKS.md](../READING-BENCHMARKS.md) first.
4
4
 
5
5
  ## What adopting this package costs
6
6
 
7
7
  For a typical workload of **640 variables** per operation, routing the work through `env-cap` adds **139 ms** per operation compared with a bare-minimum baseline (**20× the baseline**). Overall, it grows O(n) with workload size (measured exponent 0.90). At list prices that is on the order of **~$0.1 – $10 per million operations** of compute.
8
8
 
9
- > The relative figure and the growth class are the steadier ones: both come from the same run, so they depend far less on the machine than a time does, though runtime behaviour and contention on the runner still move them. The growth class is an empirical fit to the sizes tested, not a proof of asymptotic complexity. Dollar figures are **order-of-magnitude** estimates from published list prices on shared hardware (see _Cost model_ below) -- good for comparing one package with another, not for budgeting.
9
+ > The relative figure and the growth class are the steadier ones. Both come from the same run, so they depend far less on the machine than a time does. Runtime behaviour and contention on the runner still move them. The growth class is an empirical fit to the sizes tested, not a proof of asymptotic complexity. Dollar figures are **order-of-magnitude** estimates from published list prices on shared hardware (see _Cost model_ below). They show scale, not a budget.
10
10
 
11
11
  | Cost | Typical (640 variables) | Largest (5120 variables) |
12
12
  | --- | --- | --- |
@@ -25,7 +25,7 @@ Shows what a pipeline run or a developer pays to regenerate every env-cap artifa
25
25
  - **Baseline (no package):** Walk the project directory and read every schema file as text -- no env-cap.
26
26
  - **With the package:** `generateEnvArtifacts` discovers, parses and links every schema once and writes the manifest, the documentation and the usage report.
27
27
 
28
- Both sides use empty or minimal functions on purpose, so the difference is the package's own cost -- not the cost of the work an application would plug into it. Real applications add their own work on top; this is the floor the package imposes.
28
+ Both sides use empty or minimal functions on purpose. The difference is then the package's own cost, not the cost of the work an application would plug into it. Real applications add their own work on top; this is the floor the package imposes.
29
29
 
30
30
  **Variables that could change this result**
31
31
 
@@ -38,7 +38,7 @@ Both sides use empty or minimal functions on purpose, so the difference is the p
38
38
  | artifacts requested | fixed at "manifest + docs + usage report" | Requesting fewer artifacts costs less; each standalone generator is measured below. |
39
39
  | cache state | fixed at "no incremental cache" | Every run parses from scratch; the tooling keeps no build cache. |
40
40
 
41
- The baseline is an empty or minimal function, so it costs almost nothing and the _relative_ overhead can look enormous (shown as a multiple of the baseline). Read the absolute columns -- time, CPU and dollars added -- they are what a bill and a latency budget are made of.
41
+ The baseline is an empty or minimal function, so it costs almost nothing. The _relative_ overhead can then look enormous (shown as a multiple of the baseline). Read the absolute columns (time, CPU and dollars added): they are what a bill and a latency budget are made of.
42
42
 
43
43
  | variables | Baseline | With package | Added | Added vs baseline | Added CPU | Est. $ / 1M ops |
44
44
  | --- | --- | --- | --- | --- | --- | --- |
@@ -56,7 +56,7 @@ The baseline is an empty or minimal function, so it costs almost nothing and the
56
56
 
57
57
  ## 2. Function by function
58
58
 
59
- Every function the package exposes is measured on its own across the full size ladder, then its measured growth rate is compared with the big-O we documented for it. A function whose measured class **differs** from its documented one is the most useful thing in this report: either the documentation or the code is wrong.
59
+ Every function the package exposes is measured on its own across the full size ladder. Its measured growth rate is then compared with the big-O we documented for it. A function whose measured class **differs** from its documented one is the most useful thing in this report. Either the documentation or the code is wrong.
60
60
 
61
61
  | Function | Varies | Documented | Measured | Agreement | At 640 | At 5120 |
62
62
  | --- | --- | --- | --- | --- | --- | --- |
@@ -123,7 +123,7 @@ Every function the package exposes is measured on its own across the full size l
123
123
 
124
124
  **In the end-to-end run:** Once at the start of every artifact generation.
125
125
 
126
- **Measured: O(n)** (exponent 0.88, 9 sizes) -- ✅ matches.
126
+ **Measured: O(n)** (exponent 0.88, 9 sizes): ✅ matches.
127
127
 
128
128
  | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
129
129
  | --- | --- | --- | --- | --- | --- |
@@ -164,7 +164,7 @@ How many variables each schema file declares (ten in the main sweep). With the t
164
164
 
165
165
  **Deliberately not covered**
166
166
 
167
- - **incompatible schemas** -- Files the parser cannot handle take a warning path; the benchmark uses only supported schemas.
167
+ - **incompatible schemas**: Files the parser cannot handle take a warning path; the benchmark uses only supported schemas.
168
168
 
169
169
  #### Variant `all-contracts`
170
170
 
@@ -172,7 +172,7 @@ The manifest covers every schema file in the project.
172
172
 
173
173
  **Expected for this variant: O(n log n).** Parsing and rendering are linear in the source text, but the model sorts every variable and declaration by key (contract-model.ts, compatibility.ts) so the manifest and the compatibility findings are stable, and that sort adds an n log n term that shows once the whole project is covered.
174
174
 
175
- **Measured: O(n)** (exponent 0.89, 9 sizes) -- 🟡 close (neighbouring class).
175
+ **Measured: O(n)** (exponent 0.89, 9 sizes): 🟡 close (neighbouring class).
176
176
 
177
177
  | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
178
178
  | --- | --- | --- | --- | --- | --- |
@@ -198,7 +198,7 @@ An `include` selects one schema file; discovery still walks the tree but only th
198
198
 
199
199
  **Expected for this variant: O(log n).** Only the one selected file is parsed and rendered, but the directory walk that still happens grows with the tree. Across the measured sizes it is a small, sub-linear share of the cost, so the curve rises slowly without being flat.
200
200
 
201
- **Measured: O(log n)** (exponent 0.62, 9 sizes) -- ✅ matches.
201
+ **Measured: O(log n)** (exponent 0.62, 9 sizes): ✅ matches.
202
202
 
203
203
  | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
204
204
  | --- | --- | --- | --- | --- | --- |
@@ -243,7 +243,7 @@ How many variables each schema file declares (ten in the main sweep). With the t
243
243
 
244
244
  One short description per variable.
245
245
 
246
- **Measured: O(n)** (exponent 0.73, 9 sizes) -- ✅ matches.
246
+ **Measured: O(n)** (exponent 0.73, 9 sizes): ✅ matches.
247
247
 
248
248
  | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
249
249
  | --- | --- | --- | --- | --- | --- |
@@ -267,7 +267,7 @@ How many variables each schema file declares (ten in the main sweep). With the t
267
267
 
268
268
  Long descriptions and extra documentation fields per variable (a heavily documented enterprise).
269
269
 
270
- **Measured: O(n)** (exponent 0.76, 9 sizes) -- ✅ matches.
270
+ **Measured: O(n)** (exponent 0.76, 9 sizes): ✅ matches.
271
271
 
272
272
  | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
273
273
  | --- | --- | --- | --- | --- | --- |
@@ -308,7 +308,7 @@ How many variables each schema file declares (ten in the main sweep). With the t
308
308
 
309
309
  **In the end-to-end run:** Not called by the end-to-end operation: generateEnvArtifacts builds the usage report from its shared parse, while this standalone generator parses again.
310
310
 
311
- **Measured: O(n)** (exponent 0.80, 9 sizes) -- ✅ matches.
311
+ **Measured: O(n)** (exponent 0.80, 9 sizes): ✅ matches.
312
312
 
313
313
  | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
314
314
  | --- | --- | --- | --- | --- | --- |
@@ -349,7 +349,7 @@ How many variables each schema file declares (ten in the main sweep). With the t
349
349
 
350
350
  **In the end-to-end run:** This is the end-to-end operation itself.
351
351
 
352
- **Measured: O(n)** (exponent 0.87, 9 sizes) -- ✅ matches.
352
+ **Measured: O(n)** (exponent 0.87, 9 sizes): ✅ matches.
353
353
 
354
354
  | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
355
355
  | --- | --- | --- | --- | --- | --- |
@@ -440,7 +440,7 @@ How many variables each schema file declares (ten in the main sweep). With the t
440
440
  | filesystem | fixed at "local SSD through the Node adapter" | A network or virtual filesystem adds latency per file; not covered. |
441
441
  | runtime | fixed at "Node (V8)" | Measured on Node only. |
442
442
 
443
- **Measured: O(n)** (exponent 0.77, 9 sizes) -- ✅ matches.
443
+ **Measured: O(n)** (exponent 0.77, 9 sizes): ✅ matches.
444
444
 
445
445
  | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
446
446
  | --- | --- | --- | --- | --- | --- |
@@ -527,7 +527,7 @@ No artifact exists: the model is rebuilt.
527
527
 
528
528
  **Deliberately not covered**
529
529
 
530
- - **aliased and package imports** -- Following a tsconfig alias or an allowlisted package adds a resolution per import; the fixtures import nothing.
530
+ - **aliased and package imports**: Following a tsconfig alias or an allowlisted package adds a resolution per import; the fixtures import nothing.
531
531
 
532
532
  **In the end-to-end run:** Run once inside every generator; measured on its own.
533
533
 
@@ -836,7 +836,7 @@ No artifact exists: the model is rebuilt.
836
836
  | projection shape | fixed at "five derived fields across all six fact models" | A projection that reads fewer fields still pays the clone; one that computes more adds proportional work. |
837
837
  | runtime | fixed at "Node (V8)" | Measured on Node only. |
838
838
 
839
- **Measured: O(n)** (exponent 1.07, 9 sizes) -- ✅ matches.
839
+ **Measured: O(n)** (exponent 1.07, 9 sizes): ✅ matches.
840
840
 
841
841
  | variables | Median | p95 | CPU (median) | Heap Δ | Ops/s |
842
842
  | --- | --- | --- | --- | --- | --- |
@@ -852,7 +852,7 @@ No artifact exists: the model is rebuilt.
852
852
 
853
853
  ## 3. What makes up one end-to-end operation
854
854
 
855
- Each function's measured cost is multiplied by how many times one end-to-end operation calls it. A function measured on its own includes everything it calls, so where one attributed function calls another, the nested time is subtracted from the caller (its _exclusive_ time): every moment of the operation belongs to at most one row. Shares are measured against the whole operation with the package, a figure measured directly -- not against the _added_ time, which is the small difference of two noisy medians. They are estimates (each function was measured separately); the remainder is shown as _unattributed_.
855
+ Each function's measured cost is multiplied by how many times one end-to-end operation calls it. A function measured on its own includes everything it calls. So where one attributed function calls another, the nested time is subtracted from the caller (its _exclusive_ time). Every moment of the operation then belongs to at most one row. Shares are measured against the whole operation with the package, a figure measured directly. They are not measured against the _added_ time, which is the small difference of two noisy medians. They are estimates (each function was measured separately); the remainder is shown as _unattributed_.
856
856
 
857
857
  **At 640 variables** (whole operation: 147 ms)
858
858
 
@@ -876,14 +876,14 @@ Each function's measured cost is multiplied by how many times one end-to-end ope
876
876
 
877
877
  ## Cost model
878
878
 
879
- Estimates use two bracketing price shapes: **low** = CPU-priced compute ($0.040 per vCPU-hour, billed on CPU time) and **high** = duration-and-memory-priced functions ($0.000017 per GB-second, billed on wall time, at least 128 MB reserved). Both are rounded list prices and change over time; override them in `benchmark.config.json` → `costRates` to match your platform and negotiated pricing.
879
+ Estimates use two bracketing price shapes. **Low** is CPU-priced compute ($0.040 per vCPU-hour, billed on CPU time). **High** is duration-and-memory-priced functions ($0.000017 per GB-second, billed on wall time, at least 128 MB reserved). Both are rounded list prices and change over time; override them in `benchmark.config.json` → `costRates` to match your platform and negotiated pricing.
880
880
 
881
881
  ## Environment and method
882
882
 
883
883
  - Run: `2026-10-02T00:45:43.860Z` → `2026-10-02T00:46:55.879Z` (72 s), ci
884
884
  - Machine: AMD EPYC 9V45 96-Core Processor, 4 logical core(s) (2 physical), 15990 MB RAM, linux/x64, Node v22.23.3, GitHub Actions
885
885
  - Git: `77acd16d0d0b13e9c162061da6d6f7d739436547` on `chore/no-minify-no-dist-urls` (uncommitted changes)
886
- - Sizes: 20, 40, 80, 160, 320, 640, 1280, 2560, 5120 variables -- One environment variable declared in a schema file. Schema files hold ten variables each, so 640 variables is 64 files -- a large monorepo's worth of configuration. The ladder stops at 5,120 variables (512 files) because `discoverSchemaFiles` refuses more than 1,000 files as a sanity limit, which 10,240 variables would exceed.
886
+ - Sizes: 20, 40, 80, 160, 320, 640, 1280, 2560, 5120 variables: One environment variable declared in a schema file. Schema files hold ten variables each, so 640 variables is 64 files -- a large monorepo's worth of configuration. The ladder stops at 5,120 variables (512 files) because `discoverSchemaFiles` refuses more than 1,000 files as a sanity limit, which 10,240 variables would exceed.
887
887
 
888
- **Do not compare these numbers with another machine's, another day's, or another package's.** They exist to show how _this_ package's cost changes between runs on comparable hardware and how it scales with size. See [READING-BENCHMARKS.md](../READING-BENCHMARKS.md).
888
+ **Do not compare these numbers with another machine's, another day's, or another package's.** They show how _this_ package's cost changes between runs on comparable hardware, and how it scales with size. See [READING-BENCHMARKS.md](../READING-BENCHMARKS.md).
889
889