docs: object diagrams for governance and contract governance

packages/governance/docs/contracts.puml

@@ -0,0 +1,46 @@
+@startuml contract governance
+
+Object ParamManager {
+    paramDesc[] { name, type, value }
+    --
+    +getParams()
+    +getParam()
+    -updateFoo()
+}
+
+class GovernedContract {
+    <i>verifiable</i>: Governor, params
+    --
+    +terms: { electionManager, governedParams }
+    +getState()
+    +getContractGovernor()
+    -getContractGovernor
+    -getParamManagerAccessor
+}
+note  left : calls buildParamManager(paramDesc);\nmakes paramMgr state public\nreturns paramMgr in creatorFacet
+
+class ContractGovernor {
+    <i>verifiable</i>: governedInstance, registrarInstance
+    --
+    +getRegistrar()
+    +getGovernedContract()
+    -startGovernedInstance(registrar, governed, ...)
+    validateBallotCounter()
+    validateBallotRegistrar()
+    validateBallotTimer()
+}
+note left : ContractGovernor starts GovernedContract\nholds paramManager tightly for issue creation
+
+class Registrar {
+    Questions
+    ===
+    -addQuestion()
+}
+
+GovernedContract ..> ParamManager : creates >
+GovernedContract --> ParamManager : access\nto params
+ContractGovernor ..> GovernedContract : creates >
+ContractGovernor --> Registrar
+ContractGovernor ==> ParamManager : manages\nparams
+
+@enduml

packages/governance/docs/coreArchitecture.puml

@@ -0,0 +1,80 @@
+@startuml governance invitation linkages
+
+note "Contracts have a 'C' marker.\nInvitations have an 'I'." as NC
+
+class Registrar {
+    terms: committeeSize, committeeName
+    --
+    Questions[]
+    +questionNotifier()
+    +getOpenQuestions()
+    +getBallot(handle)
+    #getVoterInvitation()
+    -getQuestionPoserInvitation
+    -addQuestion(ballotCounterInstall, question, details)
+}
+
+note "produces VoterInvitations.\nPolymorphic over BallotCounters.\nquestions are enumerable." as N1
+Registrar .. N1
+
+class BallotCounter {
+    terms\n   {ballotSpec, quorum, closingRule, tieOutcome}
+    --
+    +getDetails()
+    +getOutcome()
+    +getStats()
+    +getBallotTemplate()
+    #countVotes()
+    -submitVote()
+    -getVoterFacet()
+}
+
+note "unaware of voter registration.\n Only Registrar hands out voterFacets" as N2
+BallotCounter .. N2
+
+object BallotDetails {
+    Method { CHOOSE_N | ORDER | WEIGHT }
+    Type { ParamChange | Election | Survey }
+    --
+    question, positions, tieOutcome, maxChoices
+    quorumRule
+    closingRule: { timer, deadline }
+    ballotHandle
+    counterInstance
+}
+
+class ElectionManager {
+    Registrar
+    addQuestion()
+}
+
+object VoterFacet {
+    ---
+    submitVote(...positions)
+}
+
+interface VoterInvitation {
+    Registrar
+    --
+    getVoterFacet()
+}
+
+interface QuestionPoserInvitation {
+    Registrar
+    --
+    getVoterFacet()
+}
+
+
+ElectionManager -.[#blue]-|> Registrar : verifiable
+
+Registrar *. VoterInvitation
+Registrar *. QuestionPoserInvitation
+Registrar --> BallotCounter : creates >
+Registrar --> VoterFacet : creates >
+VoterInvitation -> VoterFacet
+Registrar -> BallotDetails : creates >
+BallotCounter <|-.[#blue]-|> BallotDetails : verifiable
+
+
+@enduml

packages/governance/docs/example.puml

@@ -0,0 +1,53 @@
+@startuml governance example
+
+package "Example with Vote Invitation" <<rectangle>> {
+  class ContractGovernor {
+      has a committee that wlll vote on questions.
+      can create binary (and other) questions.
+  }
+
+  class BinaryBallotCounter {
+      quorumThreshold, question
+      ballotHandle, closingRule
+      --
+      doesn't know who's voting.
+      knows how to count binary questions
+  }
+
+  object "Ballot FeesTo2Percent" as FeesTo2Percent {
+      Contract
+      Question: set fees at 2%?
+      Positions
+  }
+
+  object governedContract {
+    ContractGovernor
+  }
+
+  class TreasuryGovernanceRegistrar1 {
+      Questions: FeesTo2Percent, ...
+      --
+      distributed voterInvitations to creator.
+      doesn't know how questions are created.
+  }
+
+  interface memberAVoterInvitation {
+    TreasuryGovernanceRegistrar1
+  }
+
+  object memberAVoterFacet {
+    TreasuryGovernanceRegistrar1
+    --
+    castBallot(template)
+  }
+}
+
+ContractGovernor --> BinaryBallotCounter : responds to\noutcome >
+ContractGovernor -.[#blue]-|> TreasuryGovernanceRegistrar1 : verifiable
+memberAVoterInvitation --> memberAVoterFacet
+memberAVoterFacet --> FeesTo2Percent
+
+ContractGovernor ==> governedContract : creates >
+FeesTo2Percent => governedContract
+
+@enduml