So, importantly, in this iteration of the proposal (which is not quite represented in your final breakdown in the older thread, but is something of a partial move towards topics 2 and 3), system.stateVersion isn’t going to change. Users will still be expected to define it and, generally, not touch it. I could see a future proposal that pushes all the way to per-module stateVersion that gets rid of it, but I think that starting the migration of individual modules to per-module stateVersion is useful both as a baby step toward that goal and in the intermediate state as a way to make it less of a headache to touch, for those determined to touch it.
I think this is a good idea and independent of the narrow, technical thing I’m proposing here. We can try them in parallel?
Personally, I’m neutral on this. It’s probably a smell if even a relatively new Nix user can’t look at the module source and see what stateVersion does, and if that’s true then documentation doesn’t add much; what it costs is effectively maintaining a duplicate ‘implementation’ of that logic which is never machine-checked. I’m generally in favor of allowing the code to serve as documentation for implementation details (roughly, low-level information about what an option does as opposed to explanatory information about when, why, and how to use options) and I think this counts.