fix: document contract; refactor for clarity; use defensive patterns

[dckc]

@kbennett2000 made a proposal a while back to add comments; he and I refined that into #38 . I have since split out the renaming part as #45 . A question for @samsiegart @0xpatrickdev @turadg @Chris-Hibbert etc. remains: how to handle the overlap between the comments here and the walkthru prose in the contract code walk-thru in the zoe docs? Copy the comments here into the walkthru code snippets? I suppose I'll have to try it out to see what looks most natural.

@kbennett2000 rather than changing the contract surface API again (and updating the UI again), this doesn't rename Price to Pay etc. as we did in #38

What it does:

• add comments to clarify the control flow etc.,
  • note our no-use-before-define convention (in prose)
  • cite zoe overview walkthru of this code
  • cite Hardened JS docs
• feat: hoist maxItems to default from terms instead of hard-coded
• use atomicRearrange() instead of deprecated reallocate() rather than try to explain
• validate contract terms with patterns
• refactor bagValueSize() into sum() and bagCounts()
  • set off with "#region bag utilities"
• punt trace() rather than explain

[0xpatrickdev]

how to handle the overlap between the comments here and the walkthru prose in the contract code walk-thru in the zoe docs? Copy the comments here into the walkthru code snippets? I suppose I'll have to try it out to see what looks most natural.

Hard to have an opinion without seeing what the revised docs look like. I would imagine 1-2 line comments are more tenable in a docs site versus multi-line.