@agoric/swingset-vat 0.32.3-dev-9dfa568.0 → 0.32.3-dev-b8d96c7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/swingset-vat",
-  "version": "0.32.3-dev-9dfa568.0+9dfa568",
+  "version": "0.32.3-dev-b8d96c7.0+b8d96c7",
   "description": "Vat/Container Launcher",
   "type": "module",
   "main": "src/index.js",
@@ -27,15 +27,15 @@
     "@types/yargs-parser": "^21.0.0"
   },
   "dependencies": {
-    "@agoric/internal": "0.3.3-dev-9dfa568.0+9dfa568",
-    "@agoric/kmarshal": "0.1.1-dev-9dfa568.0+9dfa568",
-    "@agoric/store": "0.9.3-dev-9dfa568.0+9dfa568",
-    "@agoric/swing-store": "0.9.2-dev-9dfa568.0+9dfa568",
-    "@agoric/swingset-liveslots": "0.10.3-dev-9dfa568.0+9dfa568",
-    "@agoric/swingset-xsnap-supervisor": "0.10.3-dev-9dfa568.0+9dfa568",
-    "@agoric/time": "0.3.3-dev-9dfa568.0+9dfa568",
-    "@agoric/vat-data": "0.5.3-dev-9dfa568.0+9dfa568",
-    "@agoric/xsnap-lockdown": "0.14.1-dev-9dfa568.0+9dfa568",
+    "@agoric/internal": "0.3.3-dev-b8d96c7.0+b8d96c7",
+    "@agoric/kmarshal": "0.1.1-dev-b8d96c7.0+b8d96c7",
+    "@agoric/store": "0.9.3-dev-b8d96c7.0+b8d96c7",
+    "@agoric/swing-store": "0.9.2-dev-b8d96c7.0+b8d96c7",
+    "@agoric/swingset-liveslots": "0.10.3-dev-b8d96c7.0+b8d96c7",
+    "@agoric/swingset-xsnap-supervisor": "0.10.3-dev-b8d96c7.0+b8d96c7",
+    "@agoric/time": "0.3.3-dev-b8d96c7.0+b8d96c7",
+    "@agoric/vat-data": "0.5.3-dev-b8d96c7.0+b8d96c7",
+    "@agoric/xsnap-lockdown": "0.14.1-dev-b8d96c7.0+b8d96c7",
     "@endo/base64": "^1.0.9",
     "@endo/bundle-source": "^3.5.1",
     "@endo/captp": "^4.4.4",
@@ -102,5 +102,5 @@
   "typeCoverage": {
     "atLeast": 76.28
   },
-  "gitHead": "9dfa5685ac8f60d31802589777b0dbadc8efb8c9"
+  "gitHead": "b8d96c7314cc9edd47b960876f23a88c18f70070"
 }

package/src/controller/initializeKernel.js

@@ -100,7 +100,6 @@ export async function initializeKernel(config, kernelStorage, options = {}) {
       // the VatManager, since it isn't available until the bundle is evaluated
       assertKnownOptions(creationOptions, [
         'enablePipelining',
-        'metered',
         'managerType',
         'enableDisavow',
         'enableSetup',

package/src/controller/initializeSwingset.js

@@ -442,26 +442,24 @@ export async function initializeSwingset(
    * The host application gives us
    * config.[vats|devices].NAME.[bundle|bundleSpec|sourceSpec|bundleName] .
    * The 'bundleName' option points into
-   * config.bundles.BUNDLENAME.[bundle|bundleSpec|sourceSpec] , which can
+   * config.bundles.BUNDLENAME.[bundle|bundleSpec|sourceSpec], which can
    * also include arbitrary named bundles that will be made available to
-   * E(vatAdminService).getNamedBundleCap(bundleName) ,and temporarily as
+   * E(vatAdminService).getNamedBundleCap(bundleName), and temporarily as
    * E(vatAdminService).createVatByName(bundleName)
    *
    * The 'kconfig' we pass through to initializeKernel has
    * kconfig.[vats|devices].NAME.bundleID and
-   * kconfig.namedBundleIDs.BUNDLENAME=bundleID , which both point into
+   * kconfig.namedBundleIDs.BUNDLENAME=bundleID, which both point into
    * kconfig.idToBundle.BUNDLEID=bundle
    *
-   * @param {SwingSetConfigProperties | { bundleName: string }} desc
+   * @param {SwingSetConfigProperties} desc
    * @param {Record<string, *>} [nameToBundle]
    */
   async function getBundle(desc, nameToBundle) {
     trace(
       'getBundle',
       Object.keys(desc),
-      // @ts-expect-error optional
       desc.moduleFormat,
-      // @ts-expect-error optional
       desc.endoZipBase64Sha512 || desc.sourceSpec,
     );
 
@@ -489,8 +487,9 @@ export async function initializeSwingset(
     throw Error(`unknown mode in desc`, desc);
   }
 
-  // fires with BundleWithID: { ...bundle, id }
   /**
+   * Returns a bundle record with an "id" property from an input that might be missing it.
+   *
    * @param {EndoZipBase64Bundle & {id?: string}} bundle
    * @returns {Promise<EndoZipBase64Bundle & {id: string}>} bundle
    */
@@ -508,11 +507,9 @@ export async function initializeSwingset(
     };
   }
 
-  // fires with BundleWithID: { ...bundle, id }
-
   /**
    *
-   * @param {(SwingSetConfigProperties | { bundleName: string }) & {bundleID?: string }} desc
+   * @param {SwingSetConfigProperties & {bundleID?: string}} desc
    * @param {Record<string, EndoZipBase64Bundle>} [nameToBundle]
    */
   async function processDesc(desc, nameToBundle) {
@@ -526,14 +523,14 @@ export async function initializeSwingset(
     modes.length === 1 ||
       Fail`need =1 of bundle/bundleSpec/sourceSpec/bundleName, got ${modes}`;
     const mode = modes[0];
-    return getBundle(desc, nameToBundle)
-      .then(addBundleID)
-      .then(bundleWithID => {
-        // replace original .sourceSpec/etc with a uniform .bundleID
-        delete desc[mode];
-        desc.bundleID = bundleWithID.id;
-        return bundleWithID;
-      });
+
+    // Remove the original mode in favor of a uniform "bundleID" property.
+    const bundle = await getBundle(desc, nameToBundle);
+    const bundleWithID = await addBundleID(bundle);
+    delete desc[mode];
+    desc.bundleID = bundleWithID.id;
+
+    return bundleWithID;
   }
 
   /**

package/src/supervisors/supervisor-helper.js

@@ -32,16 +32,15 @@ function makeSupervisorDispatch(dispatch) {
   async function dispatchToVat(delivery) {
     // the (low-level) vat is responsible for giving up agency, but we still
     // protect against exceptions
-    return Promise.resolve(delivery)
-      .then(dispatch)
-      .then(
-        res => harden(['ok', res, null]),
-        err => {
-          // TODO react more thoughtfully, maybe terminate the vat
-          console.warn(`error during vat dispatch() of ${delivery}`, err);
-          return harden(['error', `${err}`, null]);
-        },
-      );
+    await null;
+    try {
+      const res = await dispatch(delivery);
+      return harden(['ok', res, null]);
+    } catch (err) {
+      // TODO react more thoughtfully, maybe terminate the vat
+      console.warn(`error during vat dispatch() of ${delivery}`, err);
+      return harden(['error', `${err}`, null]);
+    }
   }
 
   return harden(dispatchToVat);

package/src/typeGuards.js

@@ -10,38 +10,40 @@ export const ManagerType = M.or(
 
 const Bundle = M.splitRecord({ moduleType: M.string() });
 
-const SwingsetConfigOptions = {
+const VatConfigOptions = harden({
   creationOptions: M.splitRecord({}, { critical: M.boolean() }),
   parameters: M.recordOf(M.string(), M.any()),
-};
-harden(SwingsetConfigOptions);
+});
 
-const SwingSetConfigProperties = M.or(
-  M.splitRecord({ sourceSpec: M.string() }, SwingsetConfigOptions),
-  M.splitRecord({ bundleSpec: M.string() }, SwingsetConfigOptions),
-  M.splitRecord({ bundle: Bundle }, SwingsetConfigOptions),
-);
-const SwingSetConfigDescriptor = M.recordOf(
-  M.string(),
-  SwingSetConfigProperties,
-);
+const makeSwingSetConfigProperties = (required = {}, optional = {}, rest) =>
+  M.or(
+    M.splitRecord({ sourceSpec: M.string(), ...required }, optional, rest),
+    M.splitRecord({ bundleSpec: M.string(), ...required }, optional, rest),
+    M.splitRecord({ bundle: Bundle, ...required }, optional, rest),
+  );
+const makeSwingSetConfigDescriptor = (required, optional, rest) =>
+  M.recordOf(
+    M.string(),
+    makeSwingSetConfigProperties(required, optional, rest),
+  );
 
 /**
  * NOTE: this pattern suffices for PSM bootstrap,
  * but does not cover the whole SwingSet config syntax.
  *
  * {@link ./docs/configuration.md}
- * TODO: move this to swingset?
  *
  * @see SwingSetConfig
  * in ./types-external.js
  */
-export const SwingSetConfig = M.and(
-  M.splitRecord({}, { defaultManagerType: ManagerType }),
-  M.splitRecord({}, { includeDevDependencies: M.boolean() }),
-  M.splitRecord({}, { defaultReapInterval: M.number() }), // not in type decl
-  M.splitRecord({}, { snapshotInterval: M.number() }),
-  M.splitRecord({}, { vats: SwingSetConfigDescriptor }),
-  M.splitRecord({}, { bootstrap: M.string() }),
-  M.splitRecord({}, { bundles: SwingSetConfigDescriptor }),
+export const SwingSetConfig = M.splitRecord(
+  { vats: makeSwingSetConfigDescriptor(undefined, VatConfigOptions) },
+  {
+    defaultManagerType: ManagerType,
+    includeDevDependencies: M.boolean(),
+    defaultReapInterval: M.number(),
+    snapshotInterval: M.number(),
+    bootstrap: M.string(),
+    bundles: makeSwingSetConfigDescriptor(undefined, undefined, {}),
+  },
 );

package/src/types-external.js

@@ -154,27 +154,25 @@ export {};
  */
 
 /**
+ * @typedef {{ bundle: Bundle }} BundleRef a bundle object
+ * @typedef {{ bundleName: string }} BundleName a name identifying a property in the `bundles` of a SwingSetOptions object
+ * @typedef {{ bundleSpec: string }} BundleSpec a path to a bundle file
+ * @typedef {{ sourceSpec: string }} SourceSpec a package specifier such as "@agoric/swingset-vat/tools/vat-puppet.js"
+ *
  * @typedef {{
- *   sourceSpec: string // path to pre-bundled root
- * }} SourceSpec
- * @typedef {{
- *   bundleSpec: string // path to bundled code
- * }} BundleSpec
- * @typedef {{
- *   bundle: Bundle
- * }} BundleRef
- * @typedef {{
- *   bundleName: string
- * }} BundleName
- * @typedef {(SourceSpec | BundleSpec | BundleRef | BundleName ) & {
  *   bundleID?: BundleID,
- *   creationOptions?: Record<string, any>,
+ *   creationOptions?: StaticVatOptions,
  *   parameters?: Record<string, any>,
- * }} SwingSetConfigProperties
+ * }} VatConfigOptions
+ */
+/**
+ * @template [Fields=object]
+ * @typedef {(SourceSpec | BundleSpec | BundleName | BundleRef) & Fields} SwingSetConfigProperties
  */
 
 /**
- * @typedef {Record<string, SwingSetConfigProperties>} SwingSetConfigDescriptor
+ * @template [Fields=object]
+ * @typedef {Record<string, SwingSetConfigProperties<Fields>>} SwingSetConfigDescriptor
  * Where the property name is the name of the vat.  Note that
  * the `bootstrap` property names the vat that should be used as the bootstrap vat.  Although a swingset
  * configuration can designate any vat as its bootstrap vat, `loadBasedir` will always look for a file named
@@ -188,7 +186,7 @@ export {};
  * `devDependencies` of the surrounding `package.json` should be accessible to
  * bundles.
  * @property {string} [bundleCachePath] if present, SwingSet will use a bundle cache at this path
- * @property {SwingSetConfigDescriptor} vats
+ * @property {SwingSetConfigDescriptor<VatConfigOptions>} vats
  * @property {SwingSetConfigDescriptor} [bundles]
  * @property {BundleFormat} [bundleFormat] the bundle source / import bundle
  * format.
@@ -206,7 +204,7 @@ export {};
  */
 
 /**
- * @typedef {{ bundleName: string} | { bundle: Bundle } | { bundleID: BundleID } } SourceOfBundle
+ * @typedef {BundleName | BundleRef | {bundleID: BundleID}} SourceOfBundle
  */
 /**
  * @typedef { import('@agoric/swing-store').KVStore } KVStore
@@ -295,12 +293,8 @@ export {};
  * Vat Creation and Management
  *
  * @typedef { string } BundleID
- * @typedef {any} BundleCap
+ * @typedef { any } BundleCap
  * @typedef { { moduleFormat: 'endoZipBase64', endoZipBase64: string, endoZipBase64Sha512: string } } EndoZipBase64Bundle
- *
- * @typedef { unknown } Meter
- *
- * E(vatAdminService).createVat(bundle, options: DynamicVatOptions)
  */
 
 /**
@@ -326,8 +320,6 @@ export {};
  * types are then defined as amendments to this base type.
  *
  * @typedef { object } BaseVatOptions
- * @property { string } name
- * @property { * } [vatParameters]
  * @property { boolean } [enableSetup]
  *           If true, permits the vat to construct itself using the
  *           `setup()` API, which bypasses the imposition of LiveSlots but
@@ -346,6 +338,10 @@ export {};
  *            outbound syscalls so that the vat's internal state can be
  *            reconstructed via replay.  If false, no such record is kept.
  *            Defaults to true.
+ * @property { ManagerType } [managerType]
+ * @property { boolean } [neverReap]
+ *            If true, disables automatic bringOutYourDead deliveries to a vat.
+ *            Defaults to false.
  * @property { number | 'never' } [reapInterval]
  *            Trigger a bringOutYourDead after the vat has received
  *            this many deliveries. If the value is 'never',
@@ -360,7 +356,7 @@ export {};
  */
 
 /**
- * @typedef { { meter?: Meter } } OptMeter
+ * @typedef { { meter?: unknown } } OptMeter
  *        If a meter is provided, the new dynamic vat is limited to a fixed
  *        amount of computation and allocation that can occur during any
  *        given crank. Peak stack frames are limited as well. In addition,
@@ -370,14 +366,13 @@ export {};
  *        terminated. If undefined, the vat is unmetered. Static vats
  *        cannot be metered.
  *
- * @typedef { { managerType?: ManagerType } } OptManagerType
- * @typedef { BaseVatOptions & OptMeter & OptManagerType } DynamicVatOptions
+ * @typedef { BaseVatOptions & { name: string, vatParameters?: object } & OptMeter } DynamicVatOptions
  *
  * config.vats[name].creationOptions: StaticVatOptions
  *
  * @typedef { { enableDisavow?: boolean } } OptEnableDisavow
  * @typedef { { nodeOptions?: string[] } } OptNodeOptions
- * @typedef { BaseVatOptions & OptManagerType & OptEnableDisavow & OptNodeOptions } StaticVatOptions
+ * @typedef { BaseVatOptions & OptEnableDisavow & OptNodeOptions } StaticVatOptions
  *
  * @typedef { { vatParameters?: object, upgradeMessage?: string } } VatUpgradeOptions
  * @typedef { { incarnationNumber: number } } VatUpgradeResults

package/src/types-internal.js

@@ -29,7 +29,6 @@ export {};
  * @typedef { string } MeterID
  * @typedef { { meterID?: MeterID } } OptMeterID
  * @typedef { import('./types-external.js').BaseVatOptions } BaseVatOptions
- * @typedef { import('./types-external.js').OptManagerType } OptManagerType
  * @typedef { import('@agoric/swingset-liveslots').VatDeliveryObject } VatDeliveryObject
  * @typedef { import('@agoric/swingset-liveslots').VatDeliveryResult } VatDeliveryResult
  * @typedef { import('@agoric/swingset-liveslots').VatSyscallObject } VatSyscallObject
@@ -38,7 +37,7 @@ export {};
  *
  * // used by vatKeeper.setSourceAndOptions(source, RecordedVatOptions)
  *
- * @typedef { BaseVatOptions & OptMeterID & OptManagerType } InternalDynamicVatOptions
+ * @typedef { BaseVatOptions & OptMeterID } InternalDynamicVatOptions
  *
  * RecordedVatOptions is fully-specified, no optional fields
  *

package/tools/run-utils.js

@@ -53,10 +53,25 @@ export const makeRunUtils = (controller, harness) => {
   };
 
   /**
-   * @typedef {import('@endo/eventual-send').EProxy & {
-   *  sendOnly: (presence: unknown) => Record<string, (...args: any) => void>;
-   *  vat: (name: string) => Record<string, (...args: any) => Promise<any>>;
-   * }} EVProxy
+   * @typedef {import('@endo/eventual-send').EProxy | object} EVProxyMethods
+   * @property {(presence: unknown) => Record<string, (...args: any) => Promise<void>>} sendOnly
+   *   Returns a "methods proxy" for the presence that ignores the results of
+   *   each method invocation.
+   * @property {(name: string) => Record<string, (...args: any) => Promise<any>>} vat
+   *   Returns a "methods proxy" for the root object of the specified vat.
+   *   So e.g. `EV.vat('foo').m(0)` becomes
+   *   `controller.queueToVatRoot('foo', 'm', [0])`.
+   * @property {(presence: unknown) => Record<string, Promise<any>>} get
+   *   Returns a "values proxy" for the presence for which each requested
+   *   property manifests as a promise.
+   */
+  /**
+   * @typedef {import('@endo/eventual-send').EProxy & EVProxyMethods} EVProxy
+   *   Given a presence, return a "methods proxy" for which each requested
+   *   property manifests as a method that forwards its invocation through the
+   *   controller to the presence as an invocation of an identically-named method
+   *   with identical arguments (modulo passable translation).
+   *   So e.g. `EV(x).m(0)` becomes `controller.queueToVatObject(x, 'm', [0])`.
    */
 
   // IMPORTANT WARNING TO USERS OF `EV`
@@ -103,50 +118,26 @@ export const makeRunUtils = (controller, harness) => {
   // promise that can remain pending indefinitely, possibly to be settled by a
   // future message delivery.
 
+  const makeMethodsProxy = (invoker, target, voidResult = false) =>
+    new Proxy(harden({}), {
+      get: (_t, method, _rx) => {
+        const boundMethod = (...args) =>
+          queueAndRun(() => invoker(target, method, args), voidResult);
+        return harden(boundMethod);
+      },
+    });
+
   /** @type {EVProxy} */
-  // @ts-expect-error cast, approximate
   const EV = Object.assign(
-    presence =>
-      new Proxy(harden({}), {
-        get: (_t, method, _rx) => {
-          const boundMethod = (...args) =>
-            queueAndRun(() =>
-              controller.queueToVatObject(presence, method, args),
-            );
-          return harden(boundMethod);
-        },
-      }),
+    presence => makeMethodsProxy(controller.queueToVatObject, presence),
     {
-      vat: vatName =>
-        new Proxy(harden({}), {
-          get: (_t, method, _rx) => {
-            const boundMethod = (...args) =>
-              queueAndRun(() =>
-                controller.queueToVatRoot(vatName, method, args),
-              );
-            return harden(boundMethod);
-          },
-        }),
+      vat: vatName => makeMethodsProxy(controller.queueToVatRoot, vatName),
       sendOnly: presence =>
-        new Proxy(harden({}), {
-          get: (_t, method, _rx) => {
-            const boundMethod = (...args) =>
-              queueAndRun(
-                () => controller.queueToVatObject(presence, method, args),
-                true,
-              );
-            return harden(boundMethod);
-          },
-        }),
+        makeMethodsProxy(controller.queueToVatObject, presence, true),
       get: presence =>
         new Proxy(harden({}), {
-          get: (_t, pathElement, _rx) =>
-            queueAndRun(() =>
-              controller.queueToVatRoot('bootstrap', 'awaitVatObject', [
-                presence,
-                [pathElement],
-              ]),
-            ),
+          get: (_t, key, _rx) =>
+            EV.vat('bootstrap').awaitVatObject(presence, [key]),
         }),
     },
   );