clarify CoreEval vs proposal (#9468)

## Description

I was recently confused for the nth time on why writeCoreProposal wasn't
writing a proposal. Now that we model proposals in `a3p-integration`
(something proposed to stakers) I've been running into this confusion
more often.


[CoreEvalProposal](https://github.com/Agoric/agoric-sdk/blob/4491bd134d194ba5a965a6b0ff9f394563581162/golang/cosmos/x/swingset/types/swingset.pb.go#L28-L37)
has a title and `evals` which isis an array of
[CoreEval](https://github.com/Agoric/agoric-sdk/blob/4491bd134d194ba5a965a6b0ff9f394563581162/golang/cosmos/x/swingset/types/swingset.pb.go#L72-L81).
That's the thing that has permits and code, that `writeCoreProposal` is
writing out.

This names what it's creating `CoreEval`. It's not exactly the CoreEval
type but it's 1:1 with a CoreEval so I think it's warranted.

### Security Considerations

n/a

### Scaling Considerations

n/a

### Documentation Considerations

Improves clarity. I don't know what external docs need to be updated.

### Testing Considerations

CI should suffice

### Upgrade Considerations

It should be fully backwards compatible as I maintained the module
exports. I renamed a module but it shouldn't have been deep imported
anywhere.

packages/agoric-cli/test/upgrade-contract/propose-buggy-contract.js

@@ -2,7 +2,7 @@
 
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) =>
   harden({
     sourceSpec: './init-proposal.js',

packages/agoric-cli/test/upgrade-contract/propose-upgrade-contract.js

@@ -2,7 +2,7 @@
 
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) =>
   harden({
     sourceSpec: './upgrade-proposal.js',

packages/builders/scripts/inter-protocol/add-STARS.js

@@ -2,7 +2,7 @@ import { makeHelpers } from '@agoric/deploy-script-support';
 import { defaultProposalBuilder as vaultProposalBuilder } from './add-collateral-core.js';
 import { defaultProposalBuilder as oraclesProposalBuilder } from './price-feed-core.js';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const starsVaultProposalBuilder = async powers => {
   return vaultProposalBuilder(powers, {
     interchainAssetOptions: {
@@ -17,7 +17,7 @@ export const starsVaultProposalBuilder = async powers => {
   });
 };
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const starsOraclesProposalBuilder = async powers => {
   return oraclesProposalBuilder(powers, {
     AGORIC_INSTANCE_NAME: `STARS-USD price feed`,
@@ -37,7 +37,7 @@ export const starsOraclesProposalBuilder = async powers => {
 };
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('add-STARS', starsVaultProposalBuilder);
-  await writeCoreProposal('add-STARS-oracles', starsOraclesProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('add-STARS', starsVaultProposalBuilder);
+  await writeCoreEval('add-STARS-oracles', starsOraclesProposalBuilder);
 };

packages/builders/scripts/inter-protocol/add-collateral-core.js

@@ -5,7 +5,7 @@ import { getManifestForAddAssetToVault } from '@agoric/inter-protocol/src/propos
 import { getManifestForPsm } from '@agoric/inter-protocol/src/proposals/startPSM.js';
 import { makeInstallCache } from '@agoric/inter-protocol/src/proposals/utils.js';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async (
   { publishRef, install: install0, wrapInstall },
   {
@@ -62,7 +62,7 @@ export const defaultProposalBuilder = async (
   });
 };
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const psmProposalBuilder = async (
   { publishRef, install: install0, wrapInstall },
   { anchorOptions = /** @type {object} */ ({}) } = {},
@@ -104,14 +104,14 @@ export const psmProposalBuilder = async (
 };
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
 
   const tool = await makeInstallCache(homeP, {
     loadBundle: spec => import(spec),
   });
 
-  await writeCoreProposal('gov-add-collateral', defaultProposalBuilder);
-  await writeCoreProposal('gov-start-psm', opts =>
+  await writeCoreEval('gov-add-collateral', defaultProposalBuilder);
+  await writeCoreEval('gov-start-psm', opts =>
     // @ts-expect-error XXX makeInstallCache types
     psmProposalBuilder({ ...opts, wrapInstall: tool.wrapInstall }),
   );

packages/builders/scripts/inter-protocol/init-core.js

@@ -125,7 +125,7 @@ export const mainProposalBuilder = async ({
 };
 
 // Build proposal for sim-chain etc.
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async (
   { publishRef, install },
   options = {},
@@ -185,17 +185,17 @@ export const defaultProposalBuilder = async (
 };
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
 
   const tool = await makeInstallCache(homeP, {
     loadBundle: spec => import(spec),
   });
   await Promise.all([
-    writeCoreProposal('gov-econ-committee', opts =>
+    writeCoreEval('gov-econ-committee', opts =>
       // @ts-expect-error XXX makeInstallCache types
       committeeProposalBuilder({ ...opts, wrapInstall: tool.wrapInstall }),
     ),
-    writeCoreProposal('gov-amm-vaults-etc', opts =>
+    writeCoreEval('gov-amm-vaults-etc', opts =>
       // @ts-expect-error XXX makeInstallCache types
       mainProposalBuilder({ ...opts, wrapInstall: tool.wrapInstall }),
     ),

packages/builders/scripts/inter-protocol/invite-committee-core.js

@@ -4,7 +4,7 @@ import { makeHelpers } from '@agoric/deploy-script-support';
 import { getManifestForInviteCommittee } from '@agoric/inter-protocol/src/proposals/committee-proposal.js';
 
 // Build proposal for sim-chain etc.
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async (
   { publishRef, install },
   options = {},
@@ -37,6 +37,6 @@ export const defaultProposalBuilder = async (
 };
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('gov-invite-committee', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('gov-invite-committee', defaultProposalBuilder);
 };

packages/builders/scripts/inter-protocol/price-feed-core.js

@@ -11,7 +11,7 @@ export const DEFAULT_CONTRACT_TERMS = {
   maxSubmissionValue: 2n ** 256n,
 };
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async (
   { publishRef, install },
   options = {},
@@ -84,7 +84,7 @@ export const createGov = async (homeP, endowments) => {
 
   const oracleAddresses = ORACLE_ADDRESSES.split(',');
 
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
 
   const inLookup = JSON.parse(IN_BRAND_LOOKUP);
   const outLookup = JSON.parse(OUT_BRAND_LOOKUP);
@@ -98,7 +98,7 @@ export const createGov = async (homeP, endowments) => {
       brandIn: lookup(inLookup).catch(() => undefined),
       brandOut: lookup(outLookup).catch(() => undefined),
     });
-  await writeCoreProposal('gov-price-feed', proposalBuilder); // gov-price-feed.js gov-price-feed-permit.json
+  await writeCoreEval('gov-price-feed', proposalBuilder); // gov-price-feed.js gov-price-feed-permit.json
 };
 
 export default createGov;

packages/builders/scripts/orchestration/init-stakeAtom.js

@@ -1,6 +1,6 @@
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async (
   { publishRef, install },
   options = {},
@@ -29,6 +29,6 @@ export const defaultProposalBuilder = async (
 };
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('start-stakeAtom', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('start-stakeAtom', defaultProposalBuilder);
 };

packages/builders/scripts/orchestration/init-stakeBld.js

@@ -1,7 +1,7 @@
 // @ts-check
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) =>
   harden({
     sourceSpec: '@agoric/orchestration/src/proposals/start-stakeBld.js',
@@ -18,6 +18,6 @@ export const defaultProposalBuilder = async ({ publishRef, install }) =>
   });
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('start-stakeBld', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('start-stakeBld', defaultProposalBuilder);
 };

packages/builders/scripts/pegasus/init-core.js

@@ -1,6 +1,6 @@
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) =>
   harden({
     sourceSpec: '@agoric/pegasus/src/proposals/core-proposal.js',
@@ -18,6 +18,6 @@ export const defaultProposalBuilder = async ({ publishRef, install }) =>
   });
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('gov-pegasus', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('gov-pegasus', defaultProposalBuilder);
 };

packages/builders/scripts/smart-wallet/build-game1-start.js

@@ -8,7 +8,7 @@
 import { makeHelpers } from '@agoric/deploy-script-support';
 import { getManifestForGame1 } from '@agoric/smart-wallet/test/start-game1-proposal.js';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const game1ProposalBuilder = async ({ publishRef, install }) => {
   return harden({
     sourceSpec: '@agoric/smart-wallet/test/start-game1-proposal.js',
@@ -28,6 +28,6 @@ export const game1ProposalBuilder = async ({ publishRef, install }) => {
 };
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('start-game1', game1ProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('start-game1', game1ProposalBuilder);
 };

packages/builders/scripts/smart-wallet/build-wallet-factory2-upgrade.js

@@ -7,7 +7,7 @@ import { makeHelpers } from '@agoric/deploy-script-support';
  * also prints helpful instructions for copying the files and installing them.
  */
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) =>
   harden({
     sourceSpec:
@@ -23,6 +23,6 @@ export const defaultProposalBuilder = async ({ publishRef, install }) =>
   });
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('upgrade-wallet-factory', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('upgrade-wallet-factory', defaultProposalBuilder);
 };

packages/builders/scripts/smart-wallet/build-walletFactory-upgrade.js

@@ -8,7 +8,7 @@
 import { makeHelpers } from '@agoric/deploy-script-support';
 import { getManifestForUpgrade } from '@agoric/smart-wallet/src/proposals/upgrade-walletFactory-proposal.js';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) => {
   return harden({
     sourceSpec:
@@ -29,6 +29,6 @@ export const defaultProposalBuilder = async ({ publishRef, install }) => {
 };
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('upgrade-walletFactory', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('upgrade-walletFactory', defaultProposalBuilder);
 };

packages/builders/scripts/vats/add-auction.js

@@ -1,6 +1,6 @@
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async () => {
   return harden({
     sourceSpec: '@agoric/inter-protocol/src/proposals/add-auction.js',
@@ -9,6 +9,6 @@ export const defaultProposalBuilder = async () => {
 };
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('add-auction', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('add-auction', defaultProposalBuilder);
 };

packages/builders/scripts/vats/init-core.js

@@ -1,6 +1,6 @@
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) =>
   harden({
     sourceSpec: '@agoric/vats/src/core/startWalletFactory.js',
@@ -26,6 +26,6 @@ export const defaultProposalBuilder = async ({ publishRef, install }) =>
   });
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('gov-vats', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('gov-vats', defaultProposalBuilder);
 };

packages/builders/scripts/vats/init-localchain.js

@@ -1,6 +1,6 @@
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) =>
   harden({
     sourceSpec: '@agoric/vats/src/proposals/localchain-proposal.js',
@@ -15,6 +15,6 @@ export const defaultProposalBuilder = async ({ publishRef, install }) =>
   });
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('gov-localchain', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('gov-localchain', defaultProposalBuilder);
 };

packages/builders/scripts/vats/init-network.js

@@ -1,6 +1,6 @@
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) =>
   harden({
     sourceSpec: '@agoric/vats/src/proposals/network-proposal.js',
@@ -14,6 +14,6 @@ export const defaultProposalBuilder = async ({ publishRef, install }) =>
   });
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('gov-network', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('gov-network', defaultProposalBuilder);
 };

packages/builders/scripts/vats/init-orchestration.js

@@ -1,6 +1,6 @@
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) =>
   harden({
     sourceSpec: '@agoric/orchestration/src/proposals/orchestration-proposal.js',
@@ -15,6 +15,6 @@ export const defaultProposalBuilder = async ({ publishRef, install }) =>
   });
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('gov-orchestration', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('gov-orchestration', defaultProposalBuilder);
 };

packages/builders/scripts/vats/init-transfer.js

@@ -1,6 +1,6 @@
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) =>
   harden({
     sourceSpec: '@agoric/vats/src/proposals/transfer-proposal.js',

packages/builders/scripts/vats/priceFeedSupport.js

@@ -14,7 +14,7 @@ const ORACLE_ADDRESSES = [
 /**
  * modified copy of ../inter-protocol/price-feed-core.js
  *
- * @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder}
+ * @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder}
  */
 export const priceFeedProposalBuilder = async (
   { publishRef, install },

packages/builders/scripts/vats/probe-zcf-bundle.js

@@ -1,6 +1,6 @@
 import { makeHelpers } from '@agoric/deploy-script-support';
 
-/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').ProposalBuilder} */
+/** @type {import('@agoric/deploy-script-support/src/externalTypes.js').CoreEvalBuilder} */
 export const defaultProposalBuilder = async ({ publishRef, install }) =>
   harden({
     sourceSpec: '@agoric/vats/src/proposals/probeZcfBundle.js',
@@ -17,6 +17,6 @@ export const defaultProposalBuilder = async ({ publishRef, install }) =>
   });
 
 export default async (homeP, endowments) => {
-  const { writeCoreProposal } = await makeHelpers(homeP, endowments);
-  await writeCoreProposal('probeZcfBundle', defaultProposalBuilder);
+  const { writeCoreEval } = await makeHelpers(homeP, endowments);
+  await writeCoreEval('probeZcfBundle', defaultProposalBuilder);
 };