@agoric/deploy-script-support 0.10.4-u13.0 → 0.10.4-u14.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+### [0.10.4-u14.0](https://github.com/Agoric/agoric-sdk/compare/@agoric/deploy-script-support@0.10.4-u13.0...@agoric/deploy-script-support@0.10.4-u14.0) (2024-02-27)
+
+
+### Features
+
+* **deploy-script-support:** generalize `extractCoreProposalBundles` ([5de1e93](https://github.com/Agoric/agoric-sdk/commit/5de1e93747146a4c9cd4e3d3d77a0f43033c72fb))
+* **deploy-script-support:** Write out bundle file names in machine readable file ([2a68ca1](https://github.com/Agoric/agoric-sdk/commit/2a68ca148f637ca88c553b75834496ac6ebea841))
+* **extract-proposal:** organize proposals into steps ([eaa6b4f](https://github.com/Agoric/agoric-sdk/commit/eaa6b4fdc5c8ce5c377ac8ed2b88971f78641536))
+* better diagnostic for bad proposal ([19725e5](https://github.com/Agoric/agoric-sdk/commit/19725e5a132056a314d90975fffbb89053de8829))
+
+
+
 ### [0.10.4-u13.0](https://github.com/Agoric/agoric-sdk/compare/@agoric/deploy-script-support@0.10.4-u12.0...@agoric/deploy-script-support@0.10.4-u13.0) (2023-12-07)
 
 **Note:** Version bump only for package @agoric/deploy-script-support

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/deploy-script-support",
-  "version": "0.10.4-u13.0",
+  "version": "0.10.4-u14.0",
   "description": "Helpers and other support for writing deploy scripts",
   "type": "module",
   "main": "src/helpers.js",
@@ -35,12 +35,12 @@
   "homepage": "https://github.com/Agoric/agoric-sdk#readme",
   "dependencies": {
     "@agoric/assert": "^0.6.1-u11wf.0",
-    "@agoric/ertp": "^0.16.3-u13.0",
-    "@agoric/import-manager": "^0.3.12-u13.0",
-    "@agoric/internal": "^0.4.0-u13.0",
-    "@agoric/notifier": "^0.6.3-u13.0",
-    "@agoric/store": "^0.9.3-u13.0",
-    "@agoric/zoe": "^0.26.3-u13.0",
+    "@agoric/ertp": "^0.16.3-u14.0",
+    "@agoric/import-manager": "^0.3.12-u14.0",
+    "@agoric/internal": "^0.4.0-u14.0",
+    "@agoric/notifier": "^0.6.3-u14.0",
+    "@agoric/store": "^0.9.3-u14.0",
+    "@agoric/zoe": "^0.26.3-u14.0",
     "@endo/base64": "0.2.31",
     "@endo/bundle-source": "2.5.2-upstream-rollup",
     "@endo/far": "0.2.18",
@@ -50,7 +50,7 @@
     "@endo/zip": "0.2.31"
   },
   "devDependencies": {
-    "@agoric/vats": "^0.15.2-u13.0",
+    "@agoric/vats": "^0.15.2-u14.0",
     "@endo/init": "0.5.56",
     "ava": "^5.2.0",
     "import-meta-resolve": "^2.2.1"
@@ -68,5 +68,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "5a6cdeb0c18ae9700d706445acf402f8d1e873c3"
+  "gitHead": "b3a6f3374cb3bddab39fc6d6f426429cae6c29c6"
 }

package/src/coreProposalBehavior.js

@@ -8,7 +8,20 @@ const t = 'makeCoreProposalBehavior';
  * @typedef {*} BootstrapPowers
  */
 
-// These permits apply to `allPowers` in `behavior` below.
+/**
+ * @typedef {import('./externalTypes.js').ManifestBundleRef} ManifestBundleRef
+ * @typedef {[methodName: string, ...args: unknown[]]} FlatMethargs
+ * @typedef {Record<string, Record<string, unknown>>} Manifest
+ */
+
+/**
+ * These permits are expected to be the minimum powers required by the
+ * `coreProposalBehavior` function returned from `makeCoreProposalBehavior`.
+ * They are merged with all of the manifest getter's permits to produce the
+ * total permits needed by the resulting core proposal (such as might be---and
+ * generally are---written into a *-permit.json file).
+ * @see {@link ./writeCoreProposal.js}
+ */
 export const permits = {
   consume: { agoricNamesAdmin: t, vatAdminSvc: t, zoe: t },
   evaluateBundleCap: t,
@@ -23,22 +36,22 @@ export const permits = {
  * for catching bugs.  Thus, this maker must not reference any other modules or
  * definitions.
  *
- * @param {object} opts
- * @param {{ bundleName: string } | { bundleID: string }} opts.manifestBundleRef
- * @param {[string, ...unknown[]]} opts.getManifestCall
- * @param {Record<string, Record<string, unknown>>} [opts.overrideManifest]
- * @param {typeof import('@endo/far').E} opts.E
- * @param {(...args: unknown[]) => void} [opts.log]
- * @param {(ref: unknown) => Promise<unknown>} [opts.restoreRef]
+ * @param {object} inputs
+ * @param {ManifestBundleRef} inputs.manifestBundleRef
+ * @param {FlatMethargs} inputs.getManifestCall
+ * @param {Manifest} [inputs.customManifest]
+ * @param {typeof import('@endo/far').E} inputs.E
+ * @param {(...args: unknown[]) => void} [inputs.log]
+ * @param {(ref: import('./externalTypes.js').ManifestBundleRef) => Promise<import('@agoric/zoe/src/zoeService/utils.js').Installation<unknown>>} [inputs.customRestoreRef]
  * @returns {(vatPowers: unknown) => Promise<unknown>}
  */
 export const makeCoreProposalBehavior = ({
   manifestBundleRef,
-  getManifestCall,
-  overrideManifest,
+  getManifestCall: [manifestGetterName, ...manifestGetterArgs],
+  customManifest,
   E,
   log = console.info,
-  restoreRef: overrideRestoreRef,
+  customRestoreRef,
 }) => {
   const { entries, fromEntries } = Object;
 
@@ -56,10 +69,32 @@ export const makeCoreProposalBehavior = ({
     return fromEntries(ents);
   };
 
-  /** @param {ChainBootstrapSpace & BootstrapPowers & { evaluateBundleCap: any }} allPowers */
-  const behavior = async allPowers => {
-    // NOTE: If updating any of these names extracted from `allPowers`, you must
-    // change `permits` above to reflect their accessibility.
+  const makeRestoreRef = (vatAdminSvc, zoe) => {
+    /** @type {(ref: import('./externalTypes.js').ManifestBundleRef) => Promise<Installation<unknown>>} */
+    const defaultRestoreRef = async bundleRef => {
+      // extract-proposal.js creates these records, and bundleName is
+      // the optional name under which the bundle was installed into
+      // config.bundles
+      const bundleIdP =
+        'bundleName' in bundleRef
+          ? E(vatAdminSvc).getBundleIDByName(bundleRef.bundleName)
+          : bundleRef.bundleID;
+      const bundleID = await bundleIdP;
+      const label = bundleID.slice(0, 8);
+      return E(zoe).installBundleID(bundleID, label);
+    };
+    return defaultRestoreRef;
+  };
+
+  /** @param {ChainBootstrapSpace & BootstrapPowers & { evaluateBundleCap: any }} powers */
+  const coreProposalBehavior = async powers => {
+    // NOTE: `powers` is expected to match or be a superset of the above `permits` export,
+    // which should therefore be kept in sync with this deconstruction code.
+    // HOWEVER, do note that this function is invoked with at least the *union* of powers
+    // required by individual moduleBehaviors declared by the manifest getter, which is
+    // necessary so it can use `runModuleBehaviors` to provide the appropriate subset to
+    // each one (see ./writeCoreProposal.js).
+    // Handle `powers` with the requisite care.
     const {
       consume: { vatAdminSvc, zoe, agoricNamesAdmin },
       evaluateBundleCap,
@@ -67,49 +102,45 @@ export const makeCoreProposalBehavior = ({
       modules: {
         utils: { runModuleBehaviors },
       },
-    } = allPowers;
-    const [exportedGetManifest, ...manifestArgs] = getManifestCall;
-
-    const defaultRestoreRef = async ref => {
-      // extract-proposal.js creates these records, and bundleName is
-      // the name under which the bundle was installed into
-      // config.bundles
-      const p = ref.bundleName
-        ? E(vatAdminSvc).getBundleIDByName(ref.bundleName)
-        : ref.bundleID;
-      const bundleID = await p;
-      const label = bundleID.slice(0, 8);
-      return E(zoe).installBundleID(bundleID, label);
-    };
-    const restoreRef = overrideRestoreRef || defaultRestoreRef;
+    } = powers;
 
     // Get the on-chain installation containing the manifest and behaviors.
-    console.info('evaluateBundleCap', {
+    log('evaluateBundleCap', {
       manifestBundleRef,
-      exportedGetManifest,
+      manifestGetterName,
       vatAdminSvc,
     });
     let bcapP;
     if ('bundleName' in manifestBundleRef) {
       bcapP = E(vatAdminSvc).getNamedBundleCap(manifestBundleRef.bundleName);
-    } else {
+    } else if ('bundleID' in manifestBundleRef) {
       bcapP = E(vatAdminSvc).getBundleCap(manifestBundleRef.bundleID);
+    } else {
+      const keys = Reflect.ownKeys(manifestBundleRef).map(key =>
+        typeof key === 'string' ? JSON.stringify(key) : String(key),
+      );
+      const keysStr = `[${keys.join(', ')}]`;
+      throw Error(
+        `bundleRef must have own bundleName or bundleID, missing in ${keysStr}`,
+      );
     }
     const bundleCap = await bcapP;
 
-    const manifestNS = await evaluateBundleCap(bundleCap);
+    const proposalNS = await evaluateBundleCap(bundleCap);
 
-    console.error('execute', {
-      exportedGetManifest,
-      behaviors: Object.keys(manifestNS),
+    // Get the manifest and its metadata.
+    log('execute', {
+      manifestGetterName,
+      bundleExports: Object.keys(proposalNS),
     });
+    const restoreRef = customRestoreRef || makeRestoreRef(vatAdminSvc, zoe);
     const {
       manifest,
       options: rawOptions,
       installations: rawInstallations,
-    } = await manifestNS[exportedGetManifest](
+    } = await proposalNS[manifestGetterName](
       harden({ restoreRef }),
-      ...manifestArgs,
+      ...manifestGetterArgs,
     );
 
     // Await references in the options or installations.
@@ -117,20 +148,24 @@ export const makeCoreProposalBehavior = ({
       [rawOptions, rawInstallations].map(shallowlyFulfilled),
     );
 
-    // Publish the installations for behavior dependencies.
-    const installAdmin = E(agoricNamesAdmin).lookupAdmin('installation');
-    await Promise.all(
-      entries(installations || {}).map(([key, value]) => {
-        produceInstallations[key].resolve(value);
-        return E(installAdmin).update(key, value);
-      }),
-    );
+    // Publish the installations for our dependencies.
+    const installationEntries = entries(installations || {});
+    if (installationEntries.length > 0) {
+      const installAdmin = E(agoricNamesAdmin).lookupAdmin('installation');
+      await Promise.all(
+        installationEntries.map(([key, value]) => {
+          produceInstallations[key].resolve(value);
+          return E(installAdmin).update(key, value);
+        }),
+      );
+    }
 
-    // Evaluate the manifest for our behaviors.
+    // Evaluate the manifest.
     return runModuleBehaviors({
-      allPowers,
-      behaviors: manifestNS,
-      manifest: overrideManifest || manifest,
+      // Remember that `powers` may be arbitrarily broad.
+      allPowers: powers,
+      behaviors: proposalNS,
+      manifest: customManifest || manifest,
       makeConfig: (name, _permit) => {
         log('coreProposal:', name);
         return { options };
@@ -138,22 +173,31 @@ export const makeCoreProposalBehavior = ({
     });
   };
 
-  // Make the behavior the completion value.
-  return behavior;
+  return coreProposalBehavior;
 };
 
-export const makeEnactCoreProposalsFromBundleRef =
-  ({ makeCoreProposalArgs, E }) =>
-  async allPowers => {
+/**
+ * @param {object} inputs
+ * @param {Array<{ ref: ManifestBundleRef, call: FlatMethargs, customManifest?: Manifest }>} inputs.metadataRecords
+ * @param {typeof import('@endo/far').E} inputs.E
+ */
+export const makeEnactCoreProposalsFromBundleRef = ({ metadataRecords, E }) => {
+  /**
+   * @param {ChainBootstrapSpace & BootstrapPowers & { evaluateBundleCap: any }} powers
+   * @returns {Promise<void>}
+   */
+  const enactCoreProposals = async powers => {
     await Promise.all(
-      makeCoreProposalArgs.map(async ({ ref, call, overrideManifest }) => {
-        const subBehavior = makeCoreProposalBehavior({
+      metadataRecords.map(async ({ ref, call, customManifest }) => {
+        const coreProposalBehavior = makeCoreProposalBehavior({
           manifestBundleRef: ref,
           getManifestCall: call,
-          overrideManifest,
+          customManifest,
           E,
         });
-        return subBehavior(allPowers);
+        return coreProposalBehavior(powers);
       }),
     );
   };
+  return enactCoreProposals;
+};

package/src/endo-pieces-contract.js

@@ -18,6 +18,9 @@ export const start = () => {
     });
   };
 
+  /**
+   * @param {{ zoe: ERef<ZoeService> }} opts
+   */
   const makeBundler = ({ zoe }) => {
     /** @type { Map<string, [string, Uint8Array]>} */
     const nameToContent = new Map();

package/src/externalTypes.js

@@ -16,30 +16,29 @@ export {};
  */
 
 /**
- * @typedef BundleHandle
- * @property {string} [bundleName]
+ * @typedef {{fileName?: string} & ({ bundleName: string } | { bundleID: string}) } ManifestBundleRef
  */
 
 /**
  * @callback PublishBundleRef
- * @param {ERef<BundleHandle>} bundle
- * @returns {Promise<BundleHandle>}
+ * @param {ERef<ManifestBundleRef>} bundle
+ * @returns {Promise<ManifestBundleRef>}
  */
 
 /**
- * @callback InstallBundle
+ * @callback InstallEntrypoint
  * @param {string} srcSpec
- * @param {string} bundlePath
- * @param {any} [opts]
- * @returns {BundleHandle}
+ * @param {string} [bundlePath]
+ * @param {unknown} [opts]
+ * @returns {Promise<ManifestBundleRef>}
  */
 
 /**
  * @callback ProposalBuilder
  * @param {{
  *   publishRef: PublishBundleRef,
- *   install: InstallBundle,
- *   wrapInstall?: <T>(f: T) => T }
+ *   install: InstallEntrypoint,
+ *   wrapInstall?: <T extends InstallEntrypoint>(f: T) => T }
  * } powers
  * @param {...any} args
  * @returns {Promise<ProposalResult>}

package/src/extract-proposal.js

@@ -11,21 +11,47 @@ import {
 } from './coreProposalBehavior.js';
 
 /**
- * @typedef {string | { module: string, entrypoint: string, args?: Array<unknown> }} ConfigProposal
+ * @typedef {string | {module: string, entrypoint?: string, args?: Array<unknown>}} ConfigProposal
  */
 
-const { details: X, Fail } = assert;
+/**
+ * @typedef {{steps: ConfigProposal[][]}} SequentialCoreProposals
+ * @typedef {ConfigProposal[] | SequentialCoreProposals} CoreProposals
+ */
+
+const { Fail } = assert;
 
 const req = createRequire(import.meta.url);
 
+/**
+ * @param  {...(CoreProposals | undefined | null)} args
+ * @returns {SequentialCoreProposals}
+ */
+export const mergeCoreProposals = (...args) => {
+  /** @type {ConfigProposal[][]} */
+  const steps = [];
+  for (const coreProposal of args) {
+    if (!coreProposal) {
+      continue;
+    }
+    if ('steps' in coreProposal) {
+      steps.push(...coreProposal.steps);
+    } else {
+      steps.push(coreProposal);
+    }
+  }
+  return harden({ steps });
+};
+harden(mergeCoreProposals);
+
 /**
  * @param {(ModuleSpecifier | FilePath)[]} paths
  * @typedef {string} ModuleSpecifier
  * @typedef {string} FilePath
  */
 const pathResolve = (...paths) => {
-  const fileName = paths.pop();
-  assert(fileName, '>=1 paths required');
+  const fileName = /** @type {string} */ (paths.pop());
+  fileName || Fail`base name required`;
   try {
     return req.resolve(fileName, {
       paths,
@@ -40,6 +66,19 @@ const findModule = (initDir, srcSpec) =>
     ? pathResolve(initDir, srcSpec)
     : req.resolve(srcSpec);
 
+/**
+ * @param {{ bundleID?: string, bundleName?: string }} handle - mutated then hardened
+ * @param {string} sourceSpec - the specifier of a module to load
+ * @param {string} key - the key of the proposal
+ * @param {string} piece - the piece of the proposal
+ * @returns {Promise<[string, any]>}
+ */
+const namedHandleToBundleSpec = async (handle, sourceSpec, key, piece) => {
+  handle.bundleName = `coreProposal${String(key)}_${piece}`;
+  harden(handle);
+  return harden([handle.bundleName, { sourceSpec }]);
+};
+
 /**
  * Format core proposals to be run at bootstrap:
  * SwingSet `bundles` configuration
@@ -51,188 +90,227 @@ const findModule = (initDir, srcSpec) =>
  * but for sim-chain and such, they can be declared statically in
  * the chain configuration, in which case they are run at bootstrap.
  *
- * @param {ConfigProposal[]} coreProposals - governance
+ * @param {CoreProposals} coreProposals - governance
  * proposals to run at chain bootstrap for scenarios such as sim-chain.
  * @param {FilePath} [dirname]
- * @param {typeof makeEnactCoreProposalsFromBundleRef} [makeEnactCoreProposals]
- * @param {(i: number) => number} [getSequenceForProposal]
+ * @param {object} [opts]
+ * @param {typeof makeEnactCoreProposalsFromBundleRef} [opts.makeEnactCoreProposals]
+ * @param {(key: PropertyKey) => PropertyKey} [opts.getSequenceForProposal]
+ * @param {typeof namedHandleToBundleSpec} [opts.handleToBundleSpec]
  */
 export const extractCoreProposalBundles = async (
   coreProposals,
   dirname = '.',
-  makeEnactCoreProposals = makeEnactCoreProposalsFromBundleRef,
-  getSequenceForProposal,
+  opts,
 ) => {
-  if (!getSequenceForProposal) {
-    // Deterministic proposal numbers.
-    getSequenceForProposal = i => i;
-  }
+  const {
+    makeEnactCoreProposals = makeEnactCoreProposalsFromBundleRef,
+    getSequenceForProposal = key => key,
+    handleToBundleSpec = namedHandleToBundleSpec,
+  } = opts || {};
 
   dirname = pathResolve(dirname);
   dirname = await fs.promises
     .stat(dirname)
     .then(stbuf => (stbuf.isDirectory() ? dirname : path.dirname(dirname)));
 
-  /** @type {Map<{ bundleName?: string }, { source: string, bundle?: string }>} */
+  /** @type {Map<{ bundleID?: string, bundleName?: string }, { source: string, bundle?: string }>} */
   const bundleHandleToAbsolutePaths = new Map();
 
+  const proposalSteps =
+    'steps' in coreProposals ? coreProposals.steps : [coreProposals];
   const bundleToSource = new Map();
-  const extracted = await Promise.all(
-    coreProposals.map(async (coreProposal, i) => {
-      // console.debug(`Parsing core proposal:`, coreProposal);
-
-      /** @type {string} */
-      let entrypoint;
-      /** @type {unknown[]} */
-      let args;
-      /** @type {string} */
-      let module;
-      if (typeof coreProposal === 'string') {
-        module = coreProposal;
-        entrypoint = 'defaultProposalBuilder';
-        args = [];
-      } else {
-        ({ module, entrypoint, args = [] } = coreProposal);
-      }
-
-      typeof module === 'string' ||
-        Fail`coreProposal module ${module} must be string`;
-      typeof entrypoint === 'string' ||
-        Fail`coreProposal entrypoint ${entrypoint} must be string`;
-      Array.isArray(args) || Fail`coreProposal args ${args} must be array`;
-
-      const thisProposalBundleHandles = new Set();
-      assert(getSequenceForProposal);
-      const thisProposalSequence = getSequenceForProposal(i);
-      const initPath = findModule(dirname, module);
-      const initDir = path.dirname(initPath);
-      /** @type {Record<string, import('./externalTypes.js').ProposalBuilder>} */
-      const ns = await import(initPath);
-      const install = (srcSpec, bundlePath) => {
-        const absoluteSrc = findModule(initDir, srcSpec);
-        const bundleHandle = {};
-        const absolutePaths = { source: absoluteSrc };
-        if (bundlePath) {
-          const absoluteBundle = pathResolve(initDir, bundlePath);
-          absolutePaths.bundle = absoluteBundle;
-          const oldSource = bundleToSource.get(absoluteBundle);
-          if (oldSource) {
-            assert.equal(
-              oldSource,
-              absoluteSrc,
-              X`${bundlePath} already installed from ${oldSource}, now ${absoluteSrc}`,
-            );
+  const extractedSteps = await Promise.all(
+    proposalSteps.map((proposalStep, i) =>
+      Promise.all(
+        proposalStep.map(async (coreProposal, j) => {
+          const key = `${i}.${j}`;
+          // console.debug(`Parsing core proposal:`, coreProposal);
+
+          /** @type {string} */
+          let entrypoint;
+          /** @type {unknown[]} */
+          let args;
+          /** @type {string} */
+          let module;
+          if (typeof coreProposal === 'string') {
+            module = coreProposal;
+            entrypoint = 'defaultProposalBuilder';
+            args = [];
           } else {
-            bundleToSource.set(absoluteBundle, absoluteSrc);
-          }
-        }
-        // Don't harden the bundleHandle since we need to set the bundleName on
-        // its unique identity later.
-        thisProposalBundleHandles.add(bundleHandle);
-        bundleHandleToAbsolutePaths.set(bundleHandle, harden(absolutePaths));
-        return bundleHandle;
-      };
-      /** @type {import('./externalTypes.js').PublishBundleRef} */
-      const publishRef = async handleP => {
-        const handle = await handleP;
-        bundleHandleToAbsolutePaths.has(handle) ||
-          Fail`${handle} not in installed bundles`;
-        return handle;
-      };
-      const proposal = await ns[entrypoint]({ publishRef, install }, ...args);
-
-      // Add the proposal bundle handles in sorted order.
-      const bundleSpecEntries = [...thisProposalBundleHandles.keys()]
-        .map(handle => [handle, bundleHandleToAbsolutePaths.get(handle)])
-        .sort(([_hnda, { source: a }], [_hndb, { source: b }]) => {
-          if (a < b) {
-            return -1;
+            ({
+              module,
+              entrypoint = 'defaultProposalBuilder',
+              args = [],
+            } = coreProposal);
           }
-          if (a > b) {
-            return 1;
-          }
-          return 0;
-        })
-        .map(([handle, absolutePaths], j) => {
-          // Transform the bundle handle identity into a bundleName reference.
-          handle.bundleName = `coreProposal${thisProposalSequence}_${j}`;
-          harden(handle);
-
-          /** @type {[string, { sourceSpec: string }]} */
-          const specEntry = [
-            handle.bundleName,
-            { sourceSpec: absolutePaths.source },
-          ];
-          return specEntry;
-        });
-
-      // Now that we've assigned all the bundleNames and hardened the
-      // handles, we can extract the behavior bundle.
-      const { sourceSpec, getManifestCall } = await deeplyFulfilledObject(
-        harden(proposal),
-      );
-
-      const behaviorSource = pathResolve(initDir, sourceSpec);
-      const behaviors = await import(behaviorSource);
-      const [exportedGetManifest, ...manifestArgs] = getManifestCall;
-      const { manifest: overrideManifest } = await behaviors[
-        exportedGetManifest
-      ](harden({ restoreRef: () => null }), ...manifestArgs);
-
-      const behaviorBundleHandle = harden({
-        bundleName: `coreProposal${thisProposalSequence}_behaviors`,
-      });
-      const behaviorAbsolutePaths = harden({
-        source: behaviorSource,
-      });
-      bundleHandleToAbsolutePaths.set(
-        behaviorBundleHandle,
-        behaviorAbsolutePaths,
-      );
-
-      bundleSpecEntries.unshift([
-        behaviorBundleHandle.bundleName,
-        { sourceSpec: behaviorAbsolutePaths.source },
-      ]);
-
-      return harden({
-        ref: behaviorBundleHandle,
-        call: getManifestCall,
-        overrideManifest,
-        bundleSpecs: bundleSpecEntries,
-      });
-    }),
+
+          typeof module === 'string' ||
+            Fail`coreProposal module ${module} must be string`;
+          typeof entrypoint === 'string' ||
+            Fail`coreProposal entrypoint ${entrypoint} must be string`;
+          Array.isArray(args) || Fail`coreProposal args ${args} must be array`;
+
+          const thisProposalBundleHandles = new Set();
+          assert(getSequenceForProposal);
+          const thisProposalSequence = getSequenceForProposal(key);
+          const initPath = findModule(dirname, module);
+          const initDir = path.dirname(initPath);
+          /** @type {Record<string, import('./externalTypes.js').ProposalBuilder>} */
+          const ns = await import(initPath);
+          const install = (srcSpec, bundlePath) => {
+            const absoluteSrc = findModule(initDir, srcSpec);
+            const bundleHandle = {};
+            const absolutePaths = { source: absoluteSrc };
+            if (bundlePath) {
+              const absoluteBundle = pathResolve(initDir, bundlePath);
+              absolutePaths.bundle = absoluteBundle;
+              const oldSource = bundleToSource.get(absoluteBundle);
+              if (oldSource) {
+                oldSource === absoluteSrc ||
+                  Fail`${bundlePath} already installed from ${oldSource}, now ${absoluteSrc}`;
+              } else {
+                bundleToSource.set(absoluteBundle, absoluteSrc);
+              }
+            }
+            // Don't harden the bundleHandle since we need to set the bundleName on
+            // its unique identity later.
+            thisProposalBundleHandles.add(bundleHandle);
+            bundleHandleToAbsolutePaths.set(
+              bundleHandle,
+              harden(absolutePaths),
+            );
+            return bundleHandle;
+          };
+          /** @type {import('./externalTypes.js').PublishBundleRef} */
+          const publishRef = async handleP => {
+            const handle = await handleP;
+            // eslint-disable-next-line @typescript-eslint/prefer-ts-expect-error -- https://github.com/Agoric/agoric-sdk/issues/4620 */
+            // @ts-ignore xxx types
+            bundleHandleToAbsolutePaths.has(handle) ||
+              Fail`${handle} not in installed bundles`;
+            return handle;
+          };
+          const proposal = await ns[entrypoint](
+            {
+              publishRef,
+              // @ts-expect-error not statically verified to return a full obj
+              install,
+            },
+            ...args,
+          );
+
+          // Add the proposal bundle handles in sorted order.
+          const bundleSpecEntries = await Promise.all(
+            [...thisProposalBundleHandles.keys()]
+              .map(handle => [handle, bundleHandleToAbsolutePaths.get(handle)])
+              .sort(([_hnda, { source: a }], [_hndb, { source: b }]) => {
+                if (a < b) {
+                  return -1;
+                }
+                if (a > b) {
+                  return 1;
+                }
+                return 0;
+              })
+              .map(async ([handle, absolutePaths], k) => {
+                // Transform the bundle handle identity into a bundleName reference.
+                const specEntry = await handleToBundleSpec(
+                  handle,
+                  absolutePaths.source,
+                  thisProposalSequence,
+                  String(k),
+                );
+                harden(handle);
+                return specEntry;
+              }),
+          );
+
+          // Now that we've assigned all the bundleNames and hardened the
+          // handles, we can extract the behavior bundle.
+          const { sourceSpec, getManifestCall } = await deeplyFulfilledObject(
+            harden(proposal),
+          );
+
+          const proposalSource = pathResolve(initDir, sourceSpec);
+          const proposalNS = await import(proposalSource);
+          const [manifestGetterName, ...manifestGetterArgs] = getManifestCall;
+          manifestGetterName in proposalNS ||
+            Fail`proposal ${proposalSource} missing export ${manifestGetterName}`;
+          const { manifest: customManifest } = await proposalNS[
+            manifestGetterName
+          ](harden({ restoreRef: () => null }), ...manifestGetterArgs);
+
+          const behaviorBundleHandle = {};
+          const specEntry = await handleToBundleSpec(
+            behaviorBundleHandle,
+            proposalSource,
+            thisProposalSequence,
+            'proposalNS',
+          );
+          bundleSpecEntries.unshift(specEntry);
+
+          bundleHandleToAbsolutePaths.set(
+            behaviorBundleHandle,
+            harden({
+              source: proposalSource,
+            }),
+          );
+
+          return /** @type {const} */ ([
+            key,
+            {
+              ref: behaviorBundleHandle,
+              call: getManifestCall,
+              customManifest,
+              bundleSpecs: bundleSpecEntries,
+            },
+          ]);
+        }),
+      ),
+    ),
   );
 
   // Extract all the bundle specs in already-sorted order.
   const bundles = Object.fromEntries(
-    extracted.flatMap(({ bundleSpecs }) => bundleSpecs),
+    extractedSteps.flatMap(step =>
+      step.flatMap(([_key, { bundleSpecs }]) => bundleSpecs),
+    ),
   );
   harden(bundles);
 
-  // Extract the manifest references and calls.
-  const makeCPArgs = extracted.map(({ ref, call, overrideManifest }) => ({
-    ref,
-    call,
-    overrideManifest,
-  }));
-  harden(makeCPArgs);
+  const codeSteps = extractedSteps.map(extractedStep => {
+    // Extract the manifest references and calls.
+    const metadataRecords = extractedStep.map(([_key, extractedSpec]) => {
+      const { ref, call, customManifest } = extractedSpec;
+      return { ref, call, customManifest };
+    });
+    harden(metadataRecords);
 
-  const code = `\
-// This is generated by @agoric/cosmic-swingset/src/extract-proposal.js - DO NOT EDIT
+    const code = `\
+// This is generated by @agoric/deploy-script-support/src/extract-proposal.js - DO NOT EDIT
 /* eslint-disable */
 
-const makeCoreProposalArgs = harden(${stringify(makeCPArgs, true)});
-
-const makeCoreProposalBehavior = ${makeCoreProposalBehavior};
+const metadataRecords = harden(${stringify(metadataRecords, true)});
 
-(${makeEnactCoreProposals})({ makeCoreProposalArgs, E });
+// Make an enactCoreProposals function and "export" it by way of script completion value.
+// It is constructed by an IIFE to ensure the absence of global bindings for
+// makeCoreProposalBehavior and makeEnactCoreProposals (the latter referencing the former),
+// which may not be necessary but preserves behavior pre-dating
+// https://github.com/Agoric/agoric-sdk/pull/8712 .
+const enactCoreProposals = ((
+  makeCoreProposalBehavior = ${makeCoreProposalBehavior},
+  makeEnactCoreProposals = ${makeEnactCoreProposals},
+) => makeEnactCoreProposals({ metadataRecords, E }))();
+enactCoreProposals;
 `;
+    return defangAndTrim(code);
+  });
 
   // console.debug('created bundles from proposals:', coreProposals, bundles);
-  return {
+  return harden({
     bundles,
-    code: defangAndTrim(code),
+    codeSteps,
     bundleHandleToAbsolutePaths,
-  };
+  });
 };

package/src/getBundlerMaker.js

@@ -13,6 +13,9 @@
 import { E } from '@endo/far';
 import url from 'url';
 
+/** @typedef {ReturnType<import('./endo-pieces-contract.js')['start']>['publicFacet']} BundleMaker */
+/** @typedef {ReturnType<BundleMaker['makeBundler']>} Bundler */
+
 export const makeGetBundlerMaker =
   (homeP, { lookup, bundleSource }) =>
   async ({
@@ -20,6 +23,7 @@ export const makeGetBundlerMaker =
     log = console.log,
   } = {}) => {
     const { board: optionalBoard, zoe, scratch } = await homeP;
+    /** @type {() => Promise<BundleMaker>} */
     const lookupOrCreate = async () => {
       // Locate the bundler maker if any already exists at the given path.
       let bundlerMaker = await lookup(JSON.parse(BUNDLER_MAKER_LOOKUP));

package/src/offer.js

@@ -19,7 +19,7 @@ import { AmountMath } from '@agoric/ertp/src/amountMath.js';
  * @param {ERef<any>} walletAdmin - an internal type of the
  * wallet, not defined here
  * @param {ERef<ZoeService>} zoe
- * @param {ERef<Purse>} zoeInvitationPurse
+ * @param {ERef<Purse<'set'>>} zoeInvitationPurse
  */
 export const makeOfferAndFindInvitationAmount = (
   walletAdmin,
@@ -28,7 +28,7 @@ export const makeOfferAndFindInvitationAmount = (
 ) => {
   /**
    * @param {Record<string, any>} invitationDetailsCriteria
-   * @returns {Promise<Amount>} invitationAmount
+   * @returns {Promise<Amount<'set'>>} invitationAmount
    */
   const findInvitationAmount = async invitationDetailsCriteria => {
     const invitationAmount = await E(zoeInvitationPurse).getCurrentAmount();

package/src/writeCoreProposal.js

@@ -7,6 +7,25 @@ import { createBundles } from '@agoric/internal/src/node/createBundles.js';
 import { defangAndTrim, mergePermits, stringify } from './code-gen.js';
 import { makeCoreProposalBehavior, permits } from './coreProposalBehavior.js';
 
+/**
+ * @callback WriteCoreProposal
+ * @param {string} filePrefix
+ * @param {import('./externalTypes.js').ProposalBuilder} proposalBuilder
+ * @returns {Promise<void>}
+ */
+
+/**
+ *
+ * @param {*} homeP
+ * @param {*} endowments
+ * @param {{
+ *   getBundlerMaker: () => Promise<import('./getBundlerMaker.js').BundleMaker>,
+ *   getBundleSpec: (...args: *) => Promise<import('./externalTypes.js').ManifestBundleRef>,
+ *   log?: typeof console.log,
+ *   writeFile?: typeof fs.promises.writeFile
+ * }} io
+ * @returns {WriteCoreProposal}
+ */
 export const makeWriteCoreProposal = (
   homeP,
   endowments,
@@ -20,6 +39,7 @@ export const makeWriteCoreProposal = (
   const { bundleSource, pathResolve } = endowments;
 
   let bundlerCache;
+  /** @returns {import('./getBundlerMaker.js').Bundler} */
   const getBundler = () => {
     if (!bundlerCache) {
       bundlerCache = E(getBundlerMaker()).makeBundler({
@@ -32,15 +52,15 @@ export const makeWriteCoreProposal = (
   const mergeProposalPermit = async (proposal, additionalPermits) => {
     const {
       sourceSpec,
-      getManifestCall: [exportedGetManifest, ...manifestArgs],
+      getManifestCall: [manifestGetterName, ...manifestGetterArgs],
     } = proposal;
 
-    const manifestNs = await import(pathResolve(sourceSpec));
+    const proposalNS = await import(pathResolve(sourceSpec));
 
     // We only care about the manifest, not any restoreRef calls.
-    const { manifest } = await manifestNs[exportedGetManifest](
-      { restoreRef: x => `restoreRef:${x}` },
-      ...manifestArgs,
+    const { manifest } = await proposalNS[manifestGetterName](
+      harden({ restoreRef: x => `restoreRef:${x}` }),
+      ...manifestGetterArgs,
     );
 
     const mergedPermits = mergePermits(manifest);
@@ -50,8 +70,18 @@ export const makeWriteCoreProposal = (
     };
   };
 
-  let mutex = Promise.resolve();
+  let mutex =
+    /** @type {Promise<import('./externalTypes.js').ManifestBundleRef | undefined>} */ (
+      Promise.resolve()
+    );
+  /** @type {WriteCoreProposal} */
   const writeCoreProposal = async (filePrefix, proposalBuilder) => {
+    /**
+     *
+     * @param {string} entrypoint
+     * @param {string} [bundlePath]
+     * @returns {Promise<NodeModule>}
+     */
     const getBundle = async (entrypoint, bundlePath) => {
       if (!bundlePath) {
         return bundleSource(pathResolve(entrypoint));
@@ -62,20 +92,36 @@ export const makeWriteCoreProposal = (
       return ns.default;
     };
 
-    // Install an entrypoint.
+    const bundles = [];
+
+    /**
+     * Install an entrypoint.
+     *
+     * @param {string} entrypoint
+     * @param {string} [bundlePath]
+     * @param {unknown} [opts]
+     * @returns {Promise<import('./externalTypes.js').ManifestBundleRef>}
+     */
     const install = async (entrypoint, bundlePath, opts) => {
       const bundle = getBundle(entrypoint, bundlePath);
 
       // Serialise the installations.
-      mutex = E.when(mutex, () => {
+      mutex = E.when(mutex, async () => {
         // console.log('installing', { filePrefix, entrypoint, bundlePath });
-        return getBundleSpec(bundle, getBundler, opts);
+        const spec = await getBundleSpec(bundle, getBundler, opts);
+        bundles.push({
+          entrypoint,
+          ...spec,
+        });
+        return spec;
       });
+      // @ts-expect-error xxx mutex type narrowing
       return mutex;
     };
 
     // Await a reference then publish to the board.
     const cmds = [];
+    /** @param {Promise<import('./externalTypes.js').ManifestBundleRef>} refP */
     const publishRef = async refP => {
       const { fileName, ...ref } = await refP;
       if (fileName) {
@@ -93,7 +139,7 @@ export const makeWriteCoreProposal = (
     // console.log('created', { filePrefix, sourceSpec, getManifestCall });
 
     // Extract the top-level permit.
-    const { permits: proposalPermit, manifest: overrideManifest } =
+    const { permits: proposalPermit, manifest: customManifest } =
       await mergeProposalPermit(proposal, permits);
 
     // Get an install
@@ -106,10 +152,14 @@ export const makeWriteCoreProposal = (
 
 const manifestBundleRef = ${stringify(manifestBundleRef)};
 const getManifestCall = harden(${stringify(getManifestCall, true)});
-const overrideManifest = ${stringify(overrideManifest, true)};
-
-// Make the behavior the completion value.
-(${makeCoreProposalBehavior})({ manifestBundleRef, getManifestCall, overrideManifest, E });
+const customManifest = ${stringify(customManifest, true)};
+
+// Make a behavior function and "export" it by way of script completion value.
+// It is constructed by an anonymous invocation to ensure the absence of a global binding
+// for makeCoreProposalBehavior, which may not be necessary but preserves behavior pre-dating
+// https://github.com/Agoric/agoric-sdk/pull/8712 .
+const behavior = (${makeCoreProposalBehavior})({ manifestBundleRef, getManifestCall, customManifest, E });
+behavior;
 `;
 
     const trimmed = defangAndTrim(code);
@@ -125,6 +175,18 @@ const overrideManifest = ${stringify(overrideManifest, true)};
     log(`creating ${proposalJsFile}`);
     await writeFile(proposalJsFile, trimmed);
 
+    const plan = {
+      name: filePrefix,
+      script: proposalJsFile,
+      permit: proposalPermitJsonFile,
+      bundles,
+    };
+
+    await writeFile(
+      `${filePrefix}-plan.json`,
+      `${JSON.stringify(plan, null, 2)}\n`,
+    );
+
     log(`\
 You can now run a governance submission command like:
   agd tx gov submit-proposal swingset-core-eval ${proposalPermitJsonFile} ${proposalJsFile} \\