@agoric/swingset-vat 0.33.0-u19.1 → 0.33.0-u20.0

package/src/controller/controller.js

@@ -9,7 +9,7 @@ import { tmpName } from 'tmp';
 import anylogger from 'anylogger';
 import microtime from 'microtime';
 
-import { assert, Fail } from '@endo/errors';
+import { assert, q, Fail } from '@endo/errors';
 import { importBundle } from '@endo/import-bundle';
 import { initSwingStore } from '@agoric/swing-store';
 
@@ -38,12 +38,17 @@ import { makeStartSubprocessWorkerNode } from './startNodeSubprocess.js';
 
 /**
  * @import {EReturn} from '@endo/far';
+ * @import {LimitedConsole} from '@agoric/internal';
+ * @import {VatID} from '../types-internal.js';
  */
 
 /**
- * @typedef { import('../types-internal.js').VatID } VatID
+ * @typedef {Record<string, unknown> & {type: string, time?: never, monotime?: never}} SlogProps
+ * @typedef {Omit<SlogProps, 'type'> & {type?: never, seconds?: never}} SlogDurationProps
  */
 
+const { hasOwn } = Object;
+
 const endoZipBase64Sha512Shape = harden({
   moduleFormat: 'endoZipBase64',
   endoZipBase64: M.string(harden({ stringLengthLimit: Infinity })),
@@ -85,14 +90,29 @@ function makeConsole(prefixer) {
   });
 }
 
+/**
+ * A console-like object for logging. It starts as the global console but is
+ * immediately replaced with an anylogger instance dedicated to this file, and
+ * upon creation of a controller is replaced again with an anylogger dedicated
+ * to that controller (and which also emits slog entries).
+ *
+ * @type {LimitedConsole}
+ */
+let sloggingConsole = console;
+/** @type {(newConsole: LimitedConsole) => void} */
+const setSloggingConsole = newConsole => {
+  sloggingConsole = newConsole;
+};
+setSloggingConsole(makeConsole('SwingSet:controller'));
+
 /**
  * @param {unknown} e
  * @param {Promise} pr
  */
-function unhandledRejectionHandler(e, pr) {
+function onUnhandledRejection(e, pr) {
   // Don't trigger sensitive hosts (like AVA).
   pr.catch(() => {});
-  console.error('🤞 UnhandledPromiseRejection:', e);
+  sloggingConsole.error('🤞 UnhandledPromiseRejection:', e);
 }
 
 /**
@@ -123,11 +143,9 @@ export async function makeSwingsetController(
   const kvStore = kernelStorage.kvStore;
   insistStorageAPI(kvStore);
 
-  // Use ambient process.env only if caller did not specify.
-  const { env = process.env } = runtimeOptions;
-
-  // build console early so we can add console.log to diagnose early problems
   const {
+    // Use ambient process.env only if caller did not specify.
+    env = process.env,
     verbose,
     debugPrefix = '',
     slogCallbacks,
@@ -138,8 +156,7 @@ export async function makeSwingsetController(
     xsnapBundleData = makeXsnapBundleData(),
     profileVats = [],
     debugVats = [],
-  } = runtimeOptions;
-  const {
+
     bundleHandler = makeWorkerBundleHandler(
       kernelStorage.bundleStore,
       xsnapBundleData,
@@ -150,6 +167,103 @@ export async function makeSwingsetController(
     throw Error('SES must be installed before calling makeSwingsetController');
   }
 
+  /** @type {(obj: SlogProps) => void} */
+  function writeSlogObject(obj) {
+    if (!slogSender) return;
+
+    const { type, seconds, ...props } = obj;
+    const timings = {
+      // microtime gives POSIX gettimeofday() with microsecond resolution
+      time: microtime.nowDouble(),
+      // this is CLOCK_MONOTONIC, seconds since process start
+      monotime: performance.now() / 1000,
+      ...(seconds === undefined ? undefined : { seconds }),
+    };
+
+    // rearrange the fields a bit to make it more legible to humans
+    slogSender(harden({ type, ...props, ...timings }));
+  }
+
+  /**
+   * Capture an extended process in the slog, writing an entry with `type`
+   * $startLabel and then later (if the function returns successfully or calls
+   * the finish callback provided to it) another entry with `type` $endLabel and
+   * a `seconds` property valued with the total elapsed duration in seconds.
+   * Finish is implied by settlement of the function's awaited return value, so
+   * any explicit use of the finish callback MUST NOT follow that settlement.
+   *
+   * @template T
+   * @template {unknown[]} A
+   * @param {readonly [startLabel: string, endLabel: string]} labels
+   * @param {SlogDurationProps} startProps for both slog entries
+   * @param {(finish: (extraProps?: SlogDurationProps) => void, ...args: A) => (T | Promise<T>)} fn
+   * @param {unknown[] & A} args
+   * @returns {Promise<T>}
+   */
+  const slogDuration = async (labels, startProps, fn, ...args) => {
+    const [startLabel, endLabel] = labels;
+    const props = { ...startProps };
+    if (hasOwn(props, 'type') || hasOwn(props, 'seconds')) {
+      const msg = 'startProps must not include "type" or "seconds"';
+      sloggingConsole.error(Error(msg));
+      delete props.type;
+      delete props.seconds;
+    }
+    let finished = false;
+    /** @type {(extraProps?: SlogDurationProps) => void} */
+    const finish = extraProps => {
+      const seconds = (performance.now() - t0) / 1000;
+      if (finished) {
+        // `finish` should only be called once.
+        // Log a stack-bearing error instance, but throw something more opaque.
+        const msg = `slog event ${startLabel} ${q(startProps || {})} already finished; ignoring props ${q(extraProps || {})}`;
+        sloggingConsole.error(Error(msg));
+        Fail`slog event ${startLabel} already finished`;
+      }
+      finished = true;
+      if (extraProps) {
+        // Preserve extraProps as an atomic unit by deleting prior occurrences.
+        for (const name of Object.keys(extraProps)) delete props[name];
+        if (hasOwn(extraProps, 'type') || hasOwn(extraProps, 'seconds')) {
+          const msg = `extraProps ${q(extraProps)} must not include "type" or "seconds"`;
+          sloggingConsole.error(Error(msg));
+          const {
+            type: _ignoredType,
+            seconds: _ignoredSeconds,
+            ...validProps
+          } = extraProps;
+          extraProps = validProps;
+        }
+      }
+      writeSlogObject({ type: endLabel, ...props, ...extraProps, seconds });
+    };
+
+    writeSlogObject({ type: startLabel, ...props });
+    const t0 = performance.now();
+    try {
+      // We need to synchronously provide the finish function.
+      // eslint-disable-next-line @jessie.js/safe-await-separator
+      const result = await fn(finish, ...args);
+      if (!finished) finish();
+      return result;
+    } catch (cause) {
+      if (!finished) {
+        const msg = `unfinished slog event ${startLabel} ${q(startProps || {})}`;
+        sloggingConsole.error(Error(msg, { cause }));
+      }
+      throw cause;
+    }
+  };
+
+  const controllerConsole = makeConsole(`${debugPrefix}SwingSet:controller`);
+  const controllerSloggingConsole = makeLimitedConsole(level => {
+    return (...args) => {
+      controllerConsole[level](...args);
+      writeSlogObject({ type: 'console', source: 'controller', level, args });
+    };
+  });
+  setSloggingConsole(controllerSloggingConsole);
+
   const startXSnap = makeStartXSnap({
     bundleHandler,
     snapStore: kernelStorage.snapStore,
@@ -167,340 +281,316 @@ export async function makeSwingsetController(
     debugVats,
   );
 
-  function writeSlogObject(obj) {
-    if (!slogSender) {
-      // Fast path; nothing to do.
-      return;
-    }
-
-    // microtime gives POSIX gettimeofday() with microsecond resolution
-    const time = microtime.nowDouble();
-    // this is CLOCK_MONOTONIC, seconds since process start
-    const monotime = performance.now() / 1000;
-
-    // rearrange the fields a bit to make it more legible to humans
-    const timedObj = { type: undefined, ...obj, time, monotime };
-
-    // Allow the SwingSet host to do anything they want with slog messages.
-    slogSender(timedObj);
-  }
-
-  const console = makeConsole(`${debugPrefix}SwingSet:controller`);
-  // We can harden this 'console' because it's new, but if we were using the
-  // original 'console' object (which has a unique prototype), we'd have to
-  // harden(Object.getPrototypeOf(console));
-  // see https://github.com/Agoric/SES-shim/issues/292 for details
-  harden(console);
-
-  writeSlogObject({ type: 'kernel-init-start' });
-
-  writeSlogObject({ type: 'bundle-kernel-start' });
-  await null;
-  const { kernelBundle = await buildKernelBundle() } = runtimeOptions;
-  writeSlogObject({ type: 'bundle-kernel-finish' });
-
-  // FIXME: Put this somewhere better.
-  const handlers = process.listeners('unhandledRejection');
-  let haveUnhandledRejectionHandler = false;
-  for (const handler of handlers) {
-    if (handler === unhandledRejectionHandler) {
-      haveUnhandledRejectionHandler = true;
-      break;
-    }
-  }
-  if (!haveUnhandledRejectionHandler) {
-    process.on('unhandledRejection', unhandledRejectionHandler);
-  }
-
-  const kernelConsole = makeConsole(`${debugPrefix}SwingSet:kernel`);
-  const sloggingKernelConsole = makeLimitedConsole(level => {
-    return (...args) => {
-      kernelConsole[level](...args);
-      writeSlogObject({ type: 'console', source: 'kernel', level, args });
-    };
-  });
-  writeSlogObject({ type: 'import-kernel-start' });
-  const kernelNS = await importBundle(kernelBundle, {
-    filePrefix: 'kernel/...',
-    endowments: {
-      console: sloggingKernelConsole,
-      // See https://github.com/Agoric/agoric-sdk/issues/9515
-      assert: globalThis.assert,
-      require: harden(
-        what => Fail`kernelRequire unprepared to satisfy require(${what})`,
-      ),
-      URL: globalThis.Base64, // Unavailable only on XSnap
-      Base64: globalThis.Base64, // Available only on XSnap
-    },
-  });
-  const buildKernel = kernelNS.default;
-  writeSlogObject({ type: 'import-kernel-finish' });
-
-  // all vats get these in their global scope, plus a vat-specific 'console'
-  const vatEndowments = harden({});
-
-  const kernelEndowments = {
-    waitUntilQuiescent,
-    kernelStorage,
-    debugPrefix,
-    vatEndowments,
-    makeConsole,
-    startSubprocessWorkerNode,
-    startXSnap,
-    slogCallbacks,
-    writeSlogObject,
-    WeakRef,
-    FinalizationRegistry,
-    gcAndFinalize: makeGcAndFinalize(engineGC),
-    bundleHandler,
-  };
-
-  const kernelRuntimeOptions = {
-    verbose,
-    warehousePolicy,
-    overrideVatManagerOptions,
-  };
-  /** @type { ReturnType<typeof import('../kernel/kernel.js').default> } */
-  const kernel = buildKernel(
-    kernelEndowments,
-    deviceEndowments,
-    kernelRuntimeOptions,
-  );
-
-  if (runtimeOptions.verbose) {
-    kernel.kdebugEnable(true);
-  }
-
-  await kernel.start();
+  const kernelInitLabels = /** @type {const} */ ([
+    'kernel-init-start',
+    'kernel-init-finish',
+  ]);
+  const controller = await slogDuration(kernelInitLabels, {}, async () => {
+    const kernelBundle = await slogDuration(
+      ['bundle-kernel-start', 'bundle-kernel-finish'],
+      {},
+      async () => runtimeOptions.kernelBundle ?? buildKernelBundle(),
+    );
 
-  /**
-   * Validate and install a code bundle.
-   *
-   * @param {EndoZipBase64Bundle} bundle
-   * @param {BundleID} [allegedBundleID]
-   * @returns {Promise<BundleID>}
-   */
-  async function validateAndInstallBundle(bundle, allegedBundleID = undefined) {
-    // TODO The following assertion may be removed when checkBundle subsumes
-    // the responsibility to verify the permanence of a bundle's properties.
-    // https://github.com/endojs/endo/issues/1106
-    mustMatch(bundle, endoZipBase64Sha512Shape);
-    await checkBundle(bundle, computeSha512, allegedBundleID);
-    const { endoZipBase64Sha512 } = bundle;
-    assert.typeof(endoZipBase64Sha512, 'string');
-    const bundleID = `b1-${endoZipBase64Sha512}`;
-    if (allegedBundleID !== undefined) {
-      bundleID === allegedBundleID ||
-        Fail`alleged bundleID ${allegedBundleID} does not match actual ${bundleID}`;
+    // FIXME: Put this somewhere better.
+    const rejectionHandlers = process.listeners('unhandledRejection');
+    if (!rejectionHandlers.includes(onUnhandledRejection)) {
+      process.on('unhandledRejection', onUnhandledRejection);
     }
-    await kernel.installBundle(bundleID, bundle);
-    return bundleID;
-  }
-
-  // the kernel won't leak our objects into the Vats, we must do
-  // the same in this wrapper
-  const controller = harden({
-    log(str) {
-      kernel.log(str);
-    },
 
-    writeSlogObject,
-
-    dump() {
-      return deepCopyJsonable(kernel.dump());
-    },
-
-    verboseDebugMode(flag) {
-      kernel.kdebugEnable(flag);
-    },
-
-    validateAndInstallBundle,
-
-    /**
-     * Run the kernel until the policy says to stop, or the queue is empty.
-     *
-     * @param {RunPolicy} [policy] - a RunPolicy to limit the work being done
-     * @returns {Promise<number>} The number of cranks that were executed.
-     */
-    async run(policy) {
-      return kernel.run(policy);
-    },
-
-    async step() {
-      return kernel.step();
-    },
-
-    async shutdown() {
-      return kernel.shutdown();
-    },
-
-    reapAllVats() {
-      kernel.reapAllVats();
-    },
-
-    changeKernelOptions(options) {
-      kernel.changeKernelOptions(options);
-    },
-
-    getStats() {
-      return deepCopyJsonable(kernel.getStats());
-    },
-
-    getStatus() {
-      return deepCopyJsonable(kernel.getStatus());
-    },
-
-    getActivityhash() {
-      return kernelStorage.getActivityhash();
-    },
-
-    // everything beyond here is for tests, and everything should be migrated
-    // to be on this 'debug' object to make that clear
-
-    debug: {
-      addDeviceHook: kernel.addDeviceHook,
-    },
-
-    pinVatRoot(vatName) {
-      const vatID = kernel.vatNameToID(vatName);
-      const kref = kernel.getRootObject(vatID);
-      kernel.pinObject(kref);
-      kernelStorage.emitCrankHashes();
-      return kref;
-    },
-
-    kpRegisterInterest(kpid) {
-      return kernel.kpRegisterInterest(kpid);
-    },
-
-    kpStatus(kpid) {
-      return kernel.kpStatus(kpid);
-    },
-
-    kpResolution(kpid, options) {
-      const result = kernel.kpResolution(kpid, options);
-      // kpResolution does DB write (changes refcounts) so we need emitCrankHashes here
-      kernelStorage.emitCrankHashes();
-      return result;
-    },
+    const kernelConsole = makeConsole(`${debugPrefix}SwingSet:kernel`);
+    const sloggingKernelConsole = makeLimitedConsole(level => {
+      return (...args) => {
+        kernelConsole[level](...args);
+        writeSlogObject({ type: 'console', source: 'kernel', level, args });
+      };
+    });
+    const buildKernel = await slogDuration(
+      ['import-kernel-start', 'import-kernel-finish'],
+      {},
+      async () => {
+        const kernelNS = await importBundle(kernelBundle, {
+          filePrefix: 'kernel/...',
+          endowments: {
+            console: sloggingKernelConsole,
+            // See https://github.com/Agoric/agoric-sdk/issues/9515
+            assert: globalThis.assert,
+            require: harden(
+              what =>
+                Fail`kernelRequire unprepared to satisfy require(${what})`,
+            ),
+            URL: globalThis.Base64, // Unavailable only on XSnap
+            Base64: globalThis.Base64, // Available only on XSnap
+          },
+        });
+        return kernelNS.default;
+      },
+    );
 
-    vatNameToID(vatName) {
-      return kernel.vatNameToID(vatName);
-    },
-    deviceNameToID(deviceName) {
-      return kernel.deviceNameToID(deviceName);
-    },
+    const kernelEndowments = {
+      waitUntilQuiescent,
+      kernelStorage,
+      debugPrefix,
+      // all vats get these in their global scope, plus a vat-specific 'console'
+      vatEndowments: harden({}),
+      makeConsole,
+      startSubprocessWorkerNode,
+      startXSnap,
+      slogCallbacks,
+      writeSlogObject,
+      slogDuration,
+      WeakRef,
+      FinalizationRegistry,
+      gcAndFinalize: makeGcAndFinalize(engineGC),
+      bundleHandler,
+    };
+    const kernelRuntimeOptions = {
+      verbose,
+      warehousePolicy,
+      overrideVatManagerOptions,
+    };
 
-    injectQueuedUpgradeEvents: () => kernel.injectQueuedUpgradeEvents(),
+    /** @type { ReturnType<typeof import('../kernel/kernel.js').default> } */
+    const kernel = buildKernel(
+      kernelEndowments,
+      deviceEndowments,
+      kernelRuntimeOptions,
+    );
 
-    /**
-     * Queue a method call into the named vat
-     *
-     * @param {string} vatName
-     * @param {string|symbol} method
-     * @param {unknown[]} args
-     * @param {ResolutionPolicy} resultPolicy
-     */
-    queueToVatRoot(vatName, method, args = [], resultPolicy = 'ignore') {
-      const vatID = kernel.vatNameToID(vatName);
-      if (typeof method !== 'symbol') {
-        assert.typeof(method, 'string');
-      }
-      const kref = kernel.getRootObject(vatID);
-      const kpid = kernel.queueToKref(kref, method, args, resultPolicy);
-      if (kpid) {
-        kernel.kpRegisterInterest(kpid);
-      }
-      kernelStorage.emitCrankHashes();
-      return kpid;
-    },
+    await kernel.start();
 
     /**
-     * Queue a method call to an object represented by a kmarshal token
+     * Validate and install a code bundle.
      *
-     * @param {any} target
-     * @param {string|symbol} method
-     * @param {unknown[]} args
-     * @param {ResolutionPolicy} resultPolicy
+     * @param {EndoZipBase64Bundle} bundle
+     * @param {BundleID} [allegedBundleID]
+     * @returns {Promise<BundleID>}
      */
-    queueToVatObject(target, method, args = [], resultPolicy = 'ignore') {
-      const targetKref = krefOf(target);
-      assert.typeof(targetKref, 'string');
-      if (typeof method !== 'symbol') {
-        assert.typeof(method, 'string');
-      }
-      const kpid = kernel.queueToKref(targetKref, method, args, resultPolicy);
-      if (kpid) {
-        kernel.kpRegisterInterest(kpid);
+    async function validateAndInstallBundle(
+      bundle,
+      allegedBundleID = undefined,
+    ) {
+      // TODO The following assertion may be removed when checkBundle subsumes
+      // the responsibility to verify the permanence of a bundle's properties.
+      // https://github.com/endojs/endo/issues/1106
+      mustMatch(bundle, endoZipBase64Sha512Shape);
+      await checkBundle(bundle, computeSha512, allegedBundleID);
+      const { endoZipBase64Sha512 } = bundle;
+      assert.typeof(endoZipBase64Sha512, 'string');
+      const bundleID = `b1-${endoZipBase64Sha512}`;
+      if (allegedBundleID !== undefined) {
+        bundleID === allegedBundleID ||
+          Fail`alleged bundleID ${allegedBundleID} does not match actual ${bundleID}`;
       }
-      kernelStorage.emitCrankHashes();
-      return kpid;
-    },
-
-    upgradeStaticVat(vatName, shouldPauseFirst, bundleID, options = {}) {
-      const vatID = kernel.vatNameToID(vatName);
-      let pauseTarget = null;
-      if (shouldPauseFirst) {
-        pauseTarget = kslot(kernel.getRootObject(vatID));
-      }
-      if (!options.upgradeMessage) {
-        options.upgradeMessage = `vat ${vatName} upgraded`;
-      }
-      const result = controller.queueToVatRoot(
-        'vatAdmin',
-        'upgradeStaticVat',
-        [vatID, pauseTarget, bundleID, options],
-        'ignore',
-      );
-      // no emitCrankHashes here because queueToVatRoot did that
-      return result;
-    },
-
-    /**
-     * terminate a vat by ID
-     *
-     * This allows the host app to terminate any vat. The effect is
-     * equivalent to the holder of the vat's `adminNode` calling
-     * `E(adminNode).terminateWithFailure(reason)`, or the vat itself
-     * calling `vatPowers.exitVatWithFailure(reason)`. It accepts a
-     * reason capdata structure (use 'kser()' to build one), which
-     * will be included in rejection data for the promise available to
-     * `E(adminNode).done()`, just like the internal termination APIs.
-     * Note that no slots/krefs are allowed in 'reason' when
-     * terminating the vat externally.
-     *
-     * This is a superpower available only from the host app, not from
-     * within vats, since `vatID` is merely a string and can be forged
-     * trivially. The host app is responsible for supplying the right
-     * vatID to kill, by looking at the database or logs (note that
-     * vats do not know their own vatID, and `controller.vatNameToID`
-     * only works for static vats, not dynamic).
-     *
-     * This will cause state changes in the swing-store (specifically
-     * marking the vat as terminated, and rejection all its
-     * outstanding promises), which must be committed before they will
-     * be durable. Either call `hostStorage.commit()` immediately
-     * after calling this, or call `controller.run()` and *then*
-     * `hostStorage.commit()` as you would normally do in response to
-     * other I/O or timer activity.
-     *
-     * The first `controller.run()` after this call will delete all
-     * the old vat's state at once, unless you use a
-     * [`runPolicy`](../../docs/run-policy.md) to rate-limit cleanups.
-     *
-     * @param {VatID} vatID
-     * @param {SwingSetCapData} reasonCD
-     */
+      await kernel.installBundle(bundleID, bundle);
+      return bundleID;
+    }
 
-    terminateVat(vatID, reasonCD) {
-      insistCapData(reasonCD);
-      assert(reasonCD.slots.length === 0, 'no slots allowed in reason');
-      kernel.terminateVatExternally(vatID, reasonCD);
-    },
+    // the kernel won't leak our objects into the Vats, we must do
+    // the same in this wrapper
+    return harden({
+      log(str) {
+        kernel.log(str);
+      },
+
+      writeSlogObject,
+
+      slogDuration,
+
+      dump() {
+        return deepCopyJsonable(kernel.dump());
+      },
+
+      verboseDebugMode(flag) {
+        kernel.kdebugEnable(flag);
+      },
+
+      validateAndInstallBundle,
+
+      /**
+       * Run the kernel until the policy says to stop, or the queue is empty.
+       *
+       * @param {RunPolicy} [policy] - a RunPolicy to limit the work being done
+       * @returns {Promise<number>} The number of cranks that were executed.
+       */
+      async run(policy) {
+        return kernel.run(policy);
+      },
+
+      async step() {
+        return kernel.step();
+      },
+
+      async shutdown() {
+        return kernel.shutdown();
+      },
+
+      reapAllVats() {
+        kernel.reapAllVats();
+      },
+
+      changeKernelOptions(options) {
+        kernel.changeKernelOptions(options);
+      },
+
+      getStats() {
+        return kernel.getStats();
+      },
+
+      getStatus() {
+        return deepCopyJsonable(kernel.getStatus());
+      },
+
+      getActivityhash() {
+        return kernelStorage.getActivityhash();
+      },
+
+      // everything beyond here is for tests, and everything should be migrated
+      // to be on this 'debug' object to make that clear
+
+      debug: {
+        addDeviceHook: kernel.addDeviceHook,
+      },
+
+      pinVatRoot(vatName) {
+        const vatID = kernel.vatNameToID(vatName);
+        const kref = kernel.getRootObject(vatID);
+        kernel.pinObject(kref);
+        kernelStorage.emitCrankHashes();
+        return kref;
+      },
+
+      kpRegisterInterest(kpid) {
+        return kernel.kpRegisterInterest(kpid);
+      },
+
+      kpStatus(kpid) {
+        return kernel.kpStatus(kpid);
+      },
+
+      kpResolution(kpid, options) {
+        const result = kernel.kpResolution(kpid, options);
+        // kpResolution does DB write (changes refcounts) so we need emitCrankHashes here
+        kernelStorage.emitCrankHashes();
+        return result;
+      },
+
+      vatNameToID(vatName) {
+        return kernel.vatNameToID(vatName);
+      },
+      deviceNameToID(deviceName) {
+        return kernel.deviceNameToID(deviceName);
+      },
+
+      injectQueuedUpgradeEvents: () => kernel.injectQueuedUpgradeEvents(),
+
+      /**
+       * Queue a method call into the named vat
+       *
+       * @param {string} vatName
+       * @param {string|symbol} method
+       * @param {unknown[]} args
+       * @param {ResolutionPolicy} resultPolicy
+       */
+      queueToVatRoot(vatName, method, args = [], resultPolicy = 'ignore') {
+        const vatID = kernel.vatNameToID(vatName);
+        if (typeof method !== 'symbol') {
+          assert.typeof(method, 'string');
+        }
+        const kref = kernel.getRootObject(vatID);
+        const kpid = kernel.queueToKref(kref, method, args, resultPolicy);
+        if (kpid) {
+          kernel.kpRegisterInterest(kpid);
+        }
+        kernelStorage.emitCrankHashes();
+        return kpid;
+      },
+
+      /**
+       * Queue a method call to an object represented by a kmarshal token
+       *
+       * @param {any} target
+       * @param {string|symbol} method
+       * @param {unknown[]} args
+       * @param {ResolutionPolicy} resultPolicy
+       */
+      queueToVatObject(target, method, args = [], resultPolicy = 'ignore') {
+        const targetKref = krefOf(target);
+        assert.typeof(targetKref, 'string');
+        if (typeof method !== 'symbol') {
+          assert.typeof(method, 'string');
+        }
+        const kpid = kernel.queueToKref(targetKref, method, args, resultPolicy);
+        if (kpid) {
+          kernel.kpRegisterInterest(kpid);
+        }
+        kernelStorage.emitCrankHashes();
+        return kpid;
+      },
+
+      upgradeStaticVat(vatName, shouldPauseFirst, bundleID, options = {}) {
+        const vatID = kernel.vatNameToID(vatName);
+        let pauseTarget = null;
+        if (shouldPauseFirst) {
+          pauseTarget = kslot(kernel.getRootObject(vatID));
+        }
+        if (!options.upgradeMessage) {
+          options.upgradeMessage = `vat ${vatName} upgraded`;
+        }
+        const result = controller.queueToVatRoot(
+          'vatAdmin',
+          'upgradeStaticVat',
+          [vatID, pauseTarget, bundleID, options],
+          'ignore',
+        );
+        // no emitCrankHashes here because queueToVatRoot did that
+        return result;
+      },
+
+      /**
+       * terminate a vat by ID
+       *
+       * This allows the host app to terminate any vat. The effect is
+       * equivalent to the holder of the vat's `adminNode` calling
+       * `E(adminNode).terminateWithFailure(reason)`, or the vat itself
+       * calling `vatPowers.exitVatWithFailure(reason)`. It accepts a
+       * reason capdata structure (use 'kser()' to build one), which
+       * will be included in rejection data for the promise available to
+       * `E(adminNode).done()`, just like the internal termination APIs.
+       * Note that no slots/krefs are allowed in 'reason' when
+       * terminating the vat externally.
+       *
+       * This is a superpower available only from the host app, not from
+       * within vats, since `vatID` is merely a string and can be forged
+       * trivially. The host app is responsible for supplying the right
+       * vatID to kill, by looking at the database or logs (note that
+       * vats do not know their own vatID, and `controller.vatNameToID`
+       * only works for static vats, not dynamic).
+       *
+       * This will cause state changes in the swing-store (specifically
+       * marking the vat as terminated, and rejection all its
+       * outstanding promises), which must be committed before they will
+       * be durable. Either call `hostStorage.commit()` immediately
+       * after calling this, or call `controller.run()` and *then*
+       * `hostStorage.commit()` as you would normally do in response to
+       * other I/O or timer activity.
+       *
+       * The first `controller.run()` after this call will delete all
+       * the old vat's state at once, unless you use a
+       * [`runPolicy`](../../docs/run-policy.md) to rate-limit cleanups.
+       *
+       * @param {VatID} vatID
+       * @param {SwingSetCapData} reasonCD
+       */
+
+      terminateVat(vatID, reasonCD) {
+        insistCapData(reasonCD);
+        assert(reasonCD.slots.length === 0, 'no slots allowed in reason');
+        kernel.terminateVatExternally(vatID, reasonCD);
+      },
+    });
   });
 
-  writeSlogObject({ type: 'kernel-init-finish' });
-
   return controller;
 }
 /** @typedef {EReturn<typeof makeSwingsetController>} SwingsetController */