From 6b006d477e88452a263f8862ec7b405518a4f620 Mon Sep 17 00:00:00 2001
From: Chris Hibbert <hibbert@agoric.com>
Date: Thu, 26 Aug 2021 09:54:34 -0700
Subject: [PATCH] chore: minor cleanups in governParam: types, comments, harden

---
 packages/governance/src/contractGovernor.js | 20 ++++++++++----------
 packages/governance/src/governParam.js      |  3 +++
 packages/governance/src/types.js            |  6 ++++++
 3 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/packages/governance/src/contractGovernor.js b/packages/governance/src/contractGovernor.js
index f8543161669..3f25f980bcb 100644
--- a/packages/governance/src/contractGovernor.js
+++ b/packages/governance/src/contractGovernor.js
@@ -48,18 +48,18 @@ const validateBallotFromCounter = async (zoe, registrar, ballotCounter) => {
  *
  * The governedContract is responsible for supplying getParamMgrAccessor() in
  * its creatorFacet. getParamMgrAccessor() takes a ParamSpecification, which
- *  identifies the parameter to be voted on. A minimal ParamSpecification
- *  specifies the key which identifies a particular paramManager (even if
- *  there's only one) and the parameterName. The interpretation of
- *  ParamSpecification is up to the contract.
+ * identifies the parameter to be voted on. A minimal ParamSpecification
+ * specifies the key which identifies a particular paramManager (even if there's
+ * only one) and the parameterName. The interpretation of ParamSpecification is
+ * up to the contract.
  *
  * The call to startGovernedInstance() returns a facet with voteOnParamChange(),
  * which is used to create ballot questions that will automatically update
  * contract parameters if passed. This facet will usually be closely held.
  *
- * The govened contract's terms include the instance of this (governing)
- *  contract (as electionManager) so clients will be able to look up the state
- *  of the governed parameters.
+ * The governed contract's terms include the instance of this (governing)
+ * contract (as electionManager) so clients will be able to look up the state
+ * of the governed parameters.
  *
  * @type {ContractStartFn}
  */
@@ -74,7 +74,7 @@ const start = async zcf => {
   /** @type {PromiseRecord<Instance>} */
   const governedInstancePK = makePromiseKit();
 
-  // a predicate that identifies ballots created by this governor
+  // Promise for a predicate that identifies ballots created by this governor
   /** @type {PromiseRecord<CreatedBallot>} */
   const createdBallotPK = makePromiseKit();
 
@@ -92,10 +92,10 @@ const start = async zcf => {
       E.get(E(zoe).getInvitationDetails(poserInvitation)).instance,
     );
 
-    const augmentedTerms = {
+    const augmentedTerms = harden({
       ...customTerms,
       electionManager: zcf.getInstance(),
-    };
+    });
 
     const { creatorFacet, instance, publicFacet } = await E(zoe).startInstance(
       governedContractInstallation,
diff --git a/packages/governance/src/governParam.js b/packages/governance/src/governParam.js
index 7fab12b8e14..12e331eb348 100644
--- a/packages/governance/src/governParam.js
+++ b/packages/governance/src/governParam.js
@@ -45,8 +45,11 @@ const validateParamChangeBallot = details => {
   );
 };
 
+/** @type {AssertBallotConcernsQuestion} */
 const assertBallotConcernsQuestion = (paramName, ballotDetails) => {
   assert(
+    // @ts-ignore typescript isn't sure the question is a paramChangeQuestion
+    // if it isn't, the assertion will fail.
     ballotDetails.question.paramSpec.parameterName === paramName,
     X`expected ${paramName} to be included`,
   );
diff --git a/packages/governance/src/types.js b/packages/governance/src/types.js
index 6eaf2fcb22a..9e49d858e12 100644
--- a/packages/governance/src/types.js
+++ b/packages/governance/src/types.js
@@ -431,6 +431,12 @@
  *   contract
  */
 
+/**
+ * @callback AssertBallotConcernsQuestion
+ * @param {string} paramName
+ * @param {BallotDetails} ballotDetails
+ */
+
 /**
  * @callback StartGovernedContract
  * @param {RegistrarCreator} registrarCreatorFacet