clarify CoreEval vs proposal #9468

turadg · 2024-06-07T16:36:35Z

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 has a title and evals which isis an array of CoreEval. 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.

dckc

looks good.

I'd like to discuss just a bit before approving.

dckc · 2024-06-07T16:44:40Z

packages/deploy-script-support/src/helpers.js

+        getBundlerMaker: helpers.getBundlerMaker,
+      });
+    },
+    /** @deprecated use writeCoreEval */
    get writeCoreProposal() {


good to see this is is not a breaking change.

We document writeCoreProposal externally, and I'm pretty sure it's used by 3rd parties.

https://docs.agoric.com/guides/agoric-cli/#agoric-run ->
#8087 (comment)

dckc · 2024-06-07T16:47:05Z

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

-    sourceSpec: '@agoric/orchestration/src/proposals/start-stakeAtom.js',
+    sourceSpec: '@agoric/orchestration/src/core/start-stakeAtom.js',


did you consider renaming start-stakeAtom.js to stakeAtom.deploy.js as well?

ooh, I like that. so a .deploy.js is a module that exports a manifest and its referenced functions for use in a build script? I'm reluctant do to that since the module shape isn't uniform. Every export name changes from one to the next, even if certain exports are supposed to fit a pattern. Maybe if we had a new deploy module format that had a export const meta for looking things up.

Regardless, I consider all that out of scope for clarifying CoreEval vs Proposal.

dckc · 2024-06-07T17:51:16Z

thanks for the breakdown by commit

at first it looked like a lot of churn, but viewed by commit it's easy to review quickly

gibson042

Nice!

gibson042 · 2024-06-07T20:08:44Z

packages/deploy-script-support/src/writeCoreEvalParts.js

- * @param {import('./externalTypes.js').ProposalBuilder} proposalBuilder
+ * @callback WriteCoreEval write to disk the files needed for a CoreEval (permits, code, and the bundles the code loads)
+ * see CoreEval in {@link '/golang/cosmos/x/swingset/types/swingset.pb.go'}
+ * @param {string} filePrefix - name on disk


Suggested change

* @param {string} filePrefix - name on disk

* @param {string} filePrefix - name on disk (code will be written to

* ${filePrefix}.js, permits to ${filePrefix}-permit.json, and an overall

* summary to ${filePrefix}-plan.json)

gibson042 · 2024-06-07T20:33:53Z

packages/deploy-script-support/src/externalTypes.js

 * @param {{
 *   publishRef: PublishBundleRef,
 *   install: InstallEntrypoint,
 *   wrapInstall?: <T extends InstallEntrypoint>(f: T) => T }
 * } powers
 * @param {...any} args
- * @returns {Promise<ProposalResult>}
+ * @returns {Promise<{sourceSpec: string, getManifestCall: [exportedGetManifest: string, ...manifestArgs: any[]]}>}


This is a huge improvement, but I still find myself frustrated by the names.

Suggested change

* @returns {Promise<{sourceSpec: string, getManifestCall: [exportedGetManifest: string, ...manifestArgs: any[]]}>}

* @returns {Promise<{sourceSpec: string, getManifestCall: [manifestGetterName: string, ...manifestGetterArgs: any[]]}>}

or possibly

Suggested change

* @returns {Promise<{sourceSpec: string, getManifestCall: [exportedGetManifest: string, ...manifestArgs: any[]]}>}

* @returns {Promise<CoreEvalDescriptor>}

with

/** * @typedef CoreEvalDescriptor * @property {string} sourceSpec import specifier for a module * @property {[manifestGetterName: string, ...manifestGetterArgs: any[]]} getManifestCall * the name of a function exported by the module and arguments to invoke it * with in order to get a manifest (a Record that associates functions to be * invoked and permits defining bootstrap-space powers they will have access * to, see {@link ../README.md} and {@link runModuleBehaviors}) */

gibson042 · 2024-06-07T20:43:34Z

packages/deploy-script-support/src/writeCoreEvalParts.js


-    const proposalNS = await import(pathResolve(sourceSpec));
+    const evalNS = await import(pathResolve(sourceSpec));


Is the "NS" (for "[module] namespace") suffix sufficiently clear? If we're renaming anyway, perhaps something like moduleRecord or imported or namespace would be better?

I read ending NS as "namespace". We use that convention in 15 files in the repo.

but i don't feel strongly so I'll change it.

gibson042 · 2024-06-07T20:44:48Z

packages/deploy-script-support/src/writeCoreEvalParts.js

-    const proposal = await deeplyFulfilled(
-      harden(proposalBuilder({ publishRef, install })),
+    // Create the eval structure.
+    const evalParts = await deeplyFulfilled(


Naming suggestion:

Suggested change

const evalParts = await deeplyFulfilled(

const evalDescriptor = await deeplyFulfilled(

gibson042 · 2024-06-07T20:48:17Z

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

@@ -11,7 +11,7 @@ export const defaultProposalBuilder = async (
    bondDenom = 'uatom',
  } = options;
  return harden({
-    sourceSpec: '@agoric/orchestration/src/proposals/start-stakeAtom.js',
+    sourceSpec: '@agoric/orchestration/src/core/start-stakeAtom.js',


The README currently includes

There are collections of proposals in .../vats/src/proposals, smart-wallet/src/proposals, orchestration/src/proposals, pegasus/src/proposals.

and also references to specific paths. Does it merit an update?

When I went to make this change, seeing this one in the list be different, I realized we're probably better off making the change all at once across packages. I'm going to remove that filename change from this PR.

gibson042 · 2024-06-07T21:02:39Z

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

+// If we like this, move it into deploy-script-support.
+// Consider also `.permit.json` to distinguish the module shape qualifier ('permit') from the identifier. (Similarly `.plan.json`.)
+const prefix = (evalName = '') => {
+  const proposalPath = import.meta.url;
+  const left = proposalPath.lastIndexOf('/') + 1;
+  const right = proposalPath.lastIndexOf('.');
+  const filename = proposalPath.substring(left, right);
+  return `${filename}-${evalName}`;
+};


These names seems misleading to me, since the behavior is actually to suffix a base component.

Suggested change

// If we like this, move it into deploy-script-support.

// Consider also `.permit.json` to distinguish the module shape qualifier ('permit') from the identifier. (Similarly `.plan.json`.)

const prefix = (evalName = '') => {

const proposalPath = import.meta.url;

const left = proposalPath.lastIndexOf('/') + 1;

const right = proposalPath.lastIndexOf('.');

const filename = proposalPath.substring(left, right);

return `${filename}-${evalName}`;

};

// If we like this, move it into deploy-script-support.

// Consider also `.permit.json` to distinguish the module shape qualifier ('permit') from the identifier. (Similarly `.plan.json`.)

const getBaseName = (keepExtension = false) => {

const proposalPath = import.meta.url;

const baseName = proposalPath.split('/').at(-1);

return keepExtension ? baseName : baseName.replace(/[.][^.]*$/, '');

};

with

await writeCoreEval(`${getBaseName()}-gov`, defaultProposalBuilder);

The idea was "this generates the prefix for writeCoreEval". If we were to move the function out, it would be just,

const getBaseName = (proposalPath, keepExtension = false) => { const baseName = proposalPath.split('/').at(-1); return keepExtension ? baseName : baseName.replace(/[.][^.]*$/, ''); };

because we can import import.meta.url. At that point it's basically Node's path.basename. I'll drop this commit too and push a separate PR to hash out the design.

cloudflare-workers-and-pages · 2024-06-08T14:15:30Z

Deploying agoric-sdk with Cloudflare Pages

Latest commit:	`593361d`
Status:	✅ Deploy successful!
Preview URL:	https://7e56b69c.agoric-sdk.pages.dev
Branch Preview URL:	https://ta-clarify-coreeval.agoric-sdk.pages.dev

View logs

more accurate. What's built is a code/permit pair (and its bundles), not a proposal (which has a title and a list of core evals)

turadg · 2024-06-09T15:48:12Z

Build failed on ,

stage-0: loadgen: Error#1: deploy-script-support failed, cannot publish bundle: (SyntaxError#2)
…
stage-0: loadgen:   at async file:///home/runner/work/agoric-sdk/agoric-sdk/agoric-sdk/packages/agoric-cli/src/scripts.js:188:7
stage-0: loadgen:   at async tryOnOpen (file:///home/runner/work/agoric-sdk/agoric-sdk/agoric-sdk/packages/agoric-cli/src/deploy.js:155:9)
stage-0: loadgen: 
stage-0: loadgen:   SyntaxError#2: Invalid or unexpected token
stage-0: loadgen: Nested error under Error#1
stage-0: loadgen:           done ||= !!settledResult.value.done;

I suspect because of importing deeplyFulfilledObject to get around,

deeplyFulfilled erases type information endojs/endo#1257

I've reverted that change so this can merge.

turadg requested review from dckc and michaelfig June 7, 2024 16:36

dckc reviewed Jun 7, 2024

View reviewed changes

dckc approved these changes Jun 7, 2024

View reviewed changes

gibson042 approved these changes Jun 7, 2024

View reviewed changes

turadg force-pushed the ta/clarify-CoreEval branch from b6bc629 to ef80a22 Compare June 8, 2024 14:15

turadg mentioned this pull request Jun 8, 2024

move core eval scripts out of proposals #9473

Open

turadg force-pushed the ta/clarify-CoreEval branch from ef80a22 to ed37a0b Compare June 8, 2024 14:31

turadg added the automerge:rebase Automatically rebase updates, then merge label Jun 8, 2024

turadg added 7 commits June 9, 2024 08:45

chore(types): s/ProposalBuilder/CoreEvalBuilder

09fe78c

more accurate. What's built is a code/permit pair (and its bundles), not a proposal (which has a title and a list of core evals)

chore: s/writeCoreProposal/writeCoreEval

9349c1d

chore: s/writeCoreProposal/writeCoreEval

03c6382

refactor: remove Proposal terminology

f6b46c5

refactor: rename writeCoreEvalParts for clarity

5c93775

chore(types): define CoreEvalDescriptor

16ca97e

refactor: naming

593361d

turadg force-pushed the ta/clarify-CoreEval branch from ed37a0b to 593361d Compare June 9, 2024 15:45

mergify bot merged commit 721b875 into master Jun 9, 2024
63 checks passed

mergify bot deleted the ta/clarify-CoreEval branch June 9, 2024 16:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

clarify CoreEval vs proposal #9468

clarify CoreEval vs proposal #9468

turadg commented Jun 7, 2024 •

edited

Loading

dckc left a comment

dckc Jun 7, 2024

dckc Jun 7, 2024

turadg Jun 7, 2024

dckc commented Jun 7, 2024

gibson042 left a comment

gibson042 Jun 7, 2024

gibson042 Jun 7, 2024

gibson042 Jun 7, 2024

turadg Jun 8, 2024

gibson042 Jun 7, 2024

gibson042 Jun 7, 2024

turadg Jun 8, 2024

turadg Jun 8, 2024

gibson042 Jun 7, 2024

turadg Jun 8, 2024

turadg Jun 8, 2024

cloudflare-workers-and-pages bot commented Jun 8, 2024 •

edited

Loading

turadg commented Jun 9, 2024

		sourceSpec: '@agoric/orchestration/src/proposals/start-stakeAtom.js',
		sourceSpec: '@agoric/orchestration/src/core/start-stakeAtom.js',

- * @param {string} filePrefix - name on disk
+ * @param {string} filePrefix - name on disk (code will be written to
+ *   ${filePrefix}.js, permits to ${filePrefix}-permit.json, and an overall
+ *   summary to ${filePrefix}-plan.json)

	* @returns {Promise<{sourceSpec: string, getManifestCall: [exportedGetManifest: string, ...manifestArgs: any[]]}>}
	* @returns {Promise<{sourceSpec: string, getManifestCall: [manifestGetterName: string, ...manifestGetterArgs: any[]]}>}

	* @returns {Promise<{sourceSpec: string, getManifestCall: [exportedGetManifest: string, ...manifestArgs: any[]]}>}
	* @returns {Promise<CoreEvalDescriptor>}


		const proposalNS = await import(pathResolve(sourceSpec));
		const evalNS = await import(pathResolve(sourceSpec));

	const evalParts = await deeplyFulfilled(
	const evalDescriptor = await deeplyFulfilled(

clarify CoreEval vs proposal #9468

clarify CoreEval vs proposal #9468

Conversation

turadg commented Jun 7, 2024 • edited Loading

Description

Security Considerations

Scaling Considerations

Documentation Considerations

Testing Considerations

Upgrade Considerations

dckc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dckc commented Jun 7, 2024

gibson042 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cloudflare-workers-and-pages bot commented Jun 8, 2024 • edited Loading

Deploying agoric-sdk with Cloudflare Pages

turadg commented Jun 9, 2024

turadg commented Jun 7, 2024 •

edited

Loading

cloudflare-workers-and-pages bot commented Jun 8, 2024 •

edited

Loading