@agoric/swingset-vat 0.32.3-dev-9bb987f.0.9bb987f → 0.32.3-dev-8d12ead.0.8d12ead

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/swingset-vat",
-  "version": "0.32.3-dev-9bb987f.0.9bb987f",
+  "version": "0.32.3-dev-8d12ead.0.8d12ead",
   "description": "Vat/Container Launcher",
   "type": "module",
   "main": "src/index.js",
@@ -22,7 +22,7 @@
     "lint:eslint": "yarn run -T eslint ."
   },
   "devDependencies": {
-    "@agoric/xsnap": "0.14.3-dev-9bb987f.0.9bb987f",
+    "@agoric/xsnap": "0.14.3-dev-8d12ead.0.8d12ead",
     "@types/better-sqlite3": "^7.6.13",
     "@types/microtime": "^2.1.0",
     "@types/tmp": "^0.2.0",
@@ -30,15 +30,15 @@
     "ava": "^5.3.0"
   },
   "dependencies": {
-    "@agoric/internal": "0.3.3-dev-9bb987f.0.9bb987f",
-    "@agoric/kmarshal": "0.1.1-dev-9bb987f.0.9bb987f",
-    "@agoric/store": "0.9.3-dev-9bb987f.0.9bb987f",
-    "@agoric/swing-store": "0.9.2-dev-9bb987f.0.9bb987f",
-    "@agoric/swingset-liveslots": "0.10.3-dev-9bb987f.0.9bb987f",
-    "@agoric/swingset-xsnap-supervisor": "0.10.3-dev-9bb987f.0.9bb987f",
-    "@agoric/time": "0.3.3-dev-9bb987f.0.9bb987f",
-    "@agoric/vat-data": "0.5.3-dev-9bb987f.0.9bb987f",
-    "@agoric/xsnap-lockdown": "0.14.1-dev-9bb987f.0.9bb987f",
+    "@agoric/internal": "0.3.3-dev-8d12ead.0.8d12ead",
+    "@agoric/kmarshal": "0.1.1-dev-8d12ead.0.8d12ead",
+    "@agoric/store": "0.9.3-dev-8d12ead.0.8d12ead",
+    "@agoric/swing-store": "0.9.2-dev-8d12ead.0.8d12ead",
+    "@agoric/swingset-liveslots": "0.10.3-dev-8d12ead.0.8d12ead",
+    "@agoric/swingset-xsnap-supervisor": "0.10.3-dev-8d12ead.0.8d12ead",
+    "@agoric/time": "0.3.3-dev-8d12ead.0.8d12ead",
+    "@agoric/vat-data": "0.5.3-dev-8d12ead.0.8d12ead",
+    "@agoric/xsnap-lockdown": "0.14.1-dev-8d12ead.0.8d12ead",
     "@endo/base64": "^1.0.12",
     "@endo/bundle-source": "^4.1.2",
     "@endo/captp": "^4.4.8",
@@ -105,5 +105,5 @@
   "typeCoverage": {
     "atLeast": 76.59
   },
-  "gitHead": "9bb987f67986eb98d04d64f5adedafc0f2d10271"
+  "gitHead": "8d12ead740e840027e28a0b6be3bf8f125adc799"
 }

package/src/kernel/kernel.js

@@ -43,8 +43,41 @@ import { makeVatAdminHooks } from './vat-admin-hooks.js';
 /**
  * @import {MeterConsumption, VatDeliveryObject, VatDeliveryResult, VatSyscallObject, VatSyscallResult} from '@agoric/swingset-liveslots';
  * @import {PolicyInputCleanupCounts} from '../types-external.js';
+ * @import {
+ *   VatID,
+ *   InternalDynamicVatOptions,
+ *   RunQueueEvent,
+ *   RunQueueEventNotify,
+ *   RunQueueEventSend,
+ *   RunQueueEventCreateVat,
+ *   RunQueueEventUpgradeVat,
+ *   RunQueueEventChangeVatOptions,
+ *   RunQueueEventStartVat,
+ *   RunQueueEventDropExports,
+ *   RunQueueEventRetireExports,
+ *   RunQueueEventRetireImports,
+ *   RunQueueEventNegatedGCAction,
+ *   RunQueueEventBringOutYourDead,
+ *   RunQueueEventCleanupTerminatedVat,
+ * } from '../types-internal.js';
  */
 
+/** @typedef {typeof gcMessageTypes[number]} GcMessageType */
+const gcMessageTypes = /** @type {const} */ ([
+  'bringOutYourDead',
+  'dropExports',
+  'retireExports',
+  'retireImports',
+]);
+
+/** @typedef {Extract<RunQueueEvent, { type: GcMessageType }>} GcMessage */
+
+/** @type {Set<RunQueueEvent['type']>} */
+const gcMessageTypesSet = new Set(gcMessageTypes);
+
+/** @type {(message: RunQueueEvent) => message is GcMessage} */
+const isGcMessage = message => gcMessageTypesSet.has(message.type);
+
 function abbreviateReplacer(_, arg) {
   if (typeof arg === 'bigint') {
     return Number(arg);
@@ -1135,33 +1168,43 @@ export default function buildKernel(
     return results;
   }
 
+  /** @type {(message: RunQueueEvent) => string} */
   function legibilizeMessage(message) {
-    if (message.type === 'send') {
-      const msg = message.msg;
-      const [method, argList] = legibilizeMessageArgs(msg.methargs);
-      const result = msg.result ? msg.result : 'null';
-      return `@${message.target} <- ${method}(${argList}) : @${result}`;
-    } else if (message.type === 'notify') {
-      return `notify(vatID: ${message.vatID}, kpid: @${message.kpid})`;
-    } else if (message.type === 'create-vat') {
-      // prettier-ignore
-      return `create-vat ${message.vatID} opts: ${JSON.stringify(message.dynamicOptions)} vatParameters: ${JSON.stringify(message.vatParameters)}`;
-    } else if (message.type === 'upgrade-vat') {
-      // prettier-ignore
-      return `upgrade-vat ${message.vatID} upgradeID: ${message.upgradeID} vatParameters: ${JSON.stringify(message.vatParameters)}`;
-    } else if (message.type === 'changeVatOptions') {
-      // prettier-ignore
-      return `changeVatOptions ${message.vatID} options: ${JSON.stringify(message.options)}`;
-    } else if (gcMessages.includes(message.type)) {
-      // prettier-ignore
-      return `${message.type} ${message.vatID} ${message.krefs.map(e=>`@${e}`).join(' ')}`;
-    } else if (
-      message.type === 'bringOutYourDead' ||
-      message.type === 'startVat'
-    ) {
-      return `${message.type} ${message.vatID}`;
-    } else {
-      return `unknown message type ${message.type}`;
+    switch (message.type) {
+      case 'send': {
+        const msg = message.msg;
+        const [method, argList] = legibilizeMessageArgs(msg.methargs);
+        const result = msg.result ? msg.result : 'null';
+        return `@${message.target} <- ${method}(${argList}) : @${result}`;
+      }
+      case 'notify':
+        return `notify(vatID: ${message.vatID}, kpid: @${message.kpid})`;
+      case 'create-vat': {
+        const optsStr = JSON.stringify(message.dynamicOptions);
+        const vatParametersStr = JSON.stringify(message.vatParameters);
+        // prettier-ignore
+        return `create-vat ${message.vatID} opts: ${optsStr} vatParameters: ${vatParametersStr}`;
+      }
+      case 'upgrade-vat': {
+        const vatParametersStr = JSON.stringify(message.vatParameters);
+        // prettier-ignore
+        return `upgrade-vat ${message.vatID} upgradeID: ${message.upgradeID} vatParameters: ${vatParametersStr}`;
+      }
+      case 'changeVatOptions':
+        // prettier-ignore
+        return `changeVatOptions ${message.vatID} options: ${JSON.stringify(message.options)}`;
+      case 'startVat':
+      case 'cleanup-terminated-vat':
+      case 'negated-gc-action':
+      case 'bringOutYourDead':
+        return `${message.type} ${message.vatID}`;
+      default:
+        if (isGcMessage(message)) {
+          const krefs = message.krefs.map(e => `@${e}`).join(' ');
+          return `${message.type} ${message.vatID} ${krefs}`;
+        }
+        // @ts-expect-error unreachable
+        return `unknown message type ${message.type}`;
     }
   }
 
@@ -1264,27 +1307,6 @@ export default function buildKernel(
     kernelKeeper.decrementRefCount(message.kpid, `deq|notify`);
   }
 
-  const gcMessages = ['dropExports', 'retireExports', 'retireImports'];
-
-  /**
-   * @typedef { import('../types-internal.js').VatID } VatID
-   * @typedef { import('../types-internal.js').InternalDynamicVatOptions } InternalDynamicVatOptions
-   *
-   * @typedef { import('../types-internal.js').RunQueueEventNotify } RunQueueEventNotify
-   * @typedef { import('../types-internal.js').RunQueueEventSend } RunQueueEventSend
-   * @typedef { import('../types-internal.js').RunQueueEventCreateVat } RunQueueEventCreateVat
-   * @typedef { import('../types-internal.js').RunQueueEventUpgradeVat } RunQueueEventUpgradeVat
-   * @typedef { import('../types-internal.js').RunQueueEventChangeVatOptions } RunQueueEventChangeVatOptions
-   * @typedef { import('../types-internal.js').RunQueueEventStartVat } RunQueueEventStartVat
-   * @typedef { import('../types-internal.js').RunQueueEventDropExports } RunQueueEventDropExports
-   * @typedef { import('../types-internal.js').RunQueueEventRetireExports } RunQueueEventRetireExports
-   * @typedef { import('../types-internal.js').RunQueueEventRetireImports } RunQueueEventRetireImports
-   * @typedef { import('../types-internal.js').RunQueueEventNegatedGCAction } RunQueueEventNegatedGCAction
-   * @typedef { import('../types-internal.js').RunQueueEventBringOutYourDead } RunQueueEventBringOutYourDead
-   * @typedef { import('../types-internal.js').RunQueueEventCleanupTerminatedVat } RunQueueEventCleanupTerminatedVat
-   * @typedef { import('../types-internal.js').RunQueueEvent } RunQueueEvent
-   */
-
   /**
    *
    * Dispatch one delivery event. Eventually, this will be called in a
@@ -1344,16 +1366,17 @@ export default function buildKernel(
       deliverP = processUpgradeVat(message);
     } else if (message.type === 'changeVatOptions') {
       deliverP = processChangeVatOptions(message);
-    } else if (message.type === 'bringOutYourDead') {
-      deliverP = processBringOutYourDead(message);
+    } else if (message.type === 'cleanup-terminated-vat') {
+      deliverP = processCleanupTerminatedVat(message);
     } else if (message.type === 'negated-gc-action') {
       // processGCActionSet pruned some negated actions, but had no GC
       // action to perform. Record the DB changes in their own crank.
-    } else if (message.type === 'cleanup-terminated-vat') {
-      deliverP = processCleanupTerminatedVat(message);
-    } else if (gcMessages.includes(message.type)) {
+    } else if (message.type === 'bringOutYourDead') {
+      deliverP = processBringOutYourDead(message);
+    } else if (isGcMessage(message)) {
       deliverP = processGCMessage(message);
     } else {
+      // @ts-expect-error unreachable
       Fail`unable to process message.type ${message.type}`;
     }
 
@@ -1369,13 +1392,16 @@ export default function buildKernel(
    */
   async function processDeliveryMessage(message) {
     const messageType = message.type;
+    const messageSummary = legibilizeMessage(message);
+    const crankNum = kernelKeeper.getCrankNumber();
+
     kdebug('');
-    // prettier-ignore
-    kdebug(`processQ crank ${kernelKeeper.getCrankNumber()} ${JSON.stringify(message)}`);
-    kdebug(legibilizeMessage(message));
+    kdebug(`processQ crank ${crankNum} ${JSON.stringify(message)}`);
+    kdebug(messageSummary);
+
     const finish = kernelSlog.startDuration(['crank-start', 'crank-finish'], {
       crankType: 'delivery',
-      crankNum: kernelKeeper.getCrankNumber(),
+      crankNum,
       messageType,
       message,
     });
@@ -1400,7 +1426,7 @@ export default function buildKernel(
 
     kernelKeeper.establishCrankSavepoint('deliver');
     const crankResults = await deliverRunQueueEvent(message);
-    // { abort/commit, deduct, terminate+notify, consumeMessage }
+    let didSnapshot = false;
 
     if (message.type === 'cleanup-terminated-vat') {
       const { cleanups } = crankResults;
@@ -1433,7 +1459,7 @@ export default function buildKernel(
     } else {
       const vatID = crankResults.didDelivery;
       if (vatID) {
-        await vatWarehouse.maybeSaveSnapshot(vatID);
+        didSnapshot = await vatWarehouse.maybeSaveSnapshot(vatID);
       }
     }
     const { computrons, meterID } = crankResults;
@@ -1475,8 +1501,18 @@ export default function buildKernel(
       queueToKref(vatAdminRootKref, method, args, 'logFailure');
     }
 
-    kernelKeeper.processRefcounts();
-    const crankNum = kernelKeeper.getCrankNumber();
+    const { lostKrefs } = kernelKeeper.processRefcounts();
+    // Lost krefs are expected for GC, but can also occur when a crank is rolled
+    // back.
+    if (lostKrefs.length && !isGcMessage(message)) {
+      const vatID = crankResults.didDelivery;
+      console.log(
+        `⚠️ Ignoring lost krefs from crankNum ${crankNum} ${vatID} ${messageSummary}${didSnapshot ? ' + snapshot' : ''}`,
+        lostKrefs,
+        message,
+        crankResults,
+      );
+    }
     kernelKeeper.incrementCrankNumber();
     const { crankhash, activityhash } = kernelKeeper.emitCrankHashes();
     finish({

package/src/kernel/state/kernelKeeper.js

@@ -221,12 +221,12 @@ export const getAllDynamicVats = getRequired => {
 const getObjectReferenceCount = (kvStore, kref) => {
   const data = kvStore.get(`${kref}.refCount`);
   if (!data) {
-    return { reachable: 0, recognizable: 0 };
+    return { exists: false, reachable: 0, recognizable: 0 };
   }
   const [reachable, recognizable] = commaSplit(data).map(Number);
   reachable <= recognizable ||
     Fail`refmismatch(get) ${kref} ${reachable},${recognizable}`;
-  return { reachable, recognizable };
+  return { exists: true, reachable, recognizable };
 };
 
 const setObjectReferenceCount = (kvStore, kref, counts) => {
@@ -1609,12 +1609,17 @@ export default function makeKernelKeeper(
   // leaving work for the next delivery.
 
   function processRefcounts() {
+    const lostKrefs = [];
     if (enableKernelGC) {
       const actions = new Set();
       for (const kref of maybeFreeKrefs.values()) {
         const { type } = parseKernelSlot(kref);
         if (type === 'promise') {
           const kpid = kref;
+          if (!hasKernelPromise(kpid)) {
+            lostKrefs.push(kref);
+            continue;
+          }
           const kp = getKernelPromise(kpid);
           if (kp.refCount === 0) {
             let idx = 0;
@@ -1633,7 +1638,10 @@ export default function makeKernelKeeper(
         }
 
         if (type === 'object') {
-          const { reachable, recognizable } = getObjectRefCount(kref);
+          const { exists, reachable, recognizable } = getObjectRefCount(kref);
+          if (!exists) {
+            lostKrefs.push(kref);
+          }
           if (reachable === 0) {
             // We avoid ownerOfKernelObject(), which will report
             // 'undefined' if the owner is dead (and being slowly
@@ -1701,6 +1709,7 @@ export default function makeKernelKeeper(
       addGCActions([...actions]);
     }
     maybeFreeKrefs.clear();
+    return { lostKrefs };
   }
 
   function createVatState(vatID, source, options) {

package/src/kernel/vat-warehouse.js

@@ -570,6 +570,7 @@ export function makeVatWarehouse({
    *
    * @param {VatID} vatID
    * @param {number} [minDeliveryCount]
+   * @returns {Promise<boolean>} whether a snapshot was saved
    */
   async function maybeSaveSnapshot(vatID, minDeliveryCount = snapshotInterval) {
     kernelKeeper.vatIsAlive(vatID) || Fail`${q(vatID)}: not alive`;

package/tools/bootstrap-relay.js

@@ -2,30 +2,45 @@
  * @file Source code for a bootstrap vat that runs blockchain behaviors (such as
  *   bridge vat integration) and exposes reflective methods for use in testing.
  *
- * TODO: Build from ./vat-puppet.js makeReflectionMethods
- * and share code with packages/vats/tools/vat-reflective-chain-bootstrap.js
+ * TODO: Share code with packages/vats/tools/bootstrap-chain-reflective.js
  * (which basically extends this for better [mock] blockchain integration).
  */
 
 import { Fail, q } from '@endo/errors';
-import { objectMap } from '@agoric/internal';
 import { Far, E } from '@endo/far';
-import { makePromiseKit } from '@endo/promise-kit';
 import { buildManualTimer } from './manual-timer.js';
+import { makeReflectionMethods } from './vat-puppet.js';
 
-export const buildRootObject = () => {
-  const timer = buildManualTimer();
+/** @import { CreateVatResults } from '../src/types-external.js' */
+
+/**
+ * @typedef {{ root: object; incarnationNumber?: number }} VatRecord
+ * @typedef {VatRecord & CreateVatResults & { bundleCap: unknown }} DynamicVatRecord
+ */
+
+export const buildRootObject = (vatPowers, bootstrapParameters, baggage) => {
+  const manualTimer = buildManualTimer();
+
+  // Captured/populated by bootstrap.
   let vatAdmin;
-  const vatData = new Map();
   const devicesByName = new Map();
-  const callLogsByRemotable = new Map();
+  /** @type {Map<string, VatRecord | DynamicVatRecord>} */
+  const vatRecords = new Map();
+
+  const reflectionMethods = makeReflectionMethods(
+    vatPowers,
+    baggage,
+    bootstrapParameters,
+  );
 
   return Far('root', {
+    ...reflectionMethods,
+
     bootstrap: async (vats, devices) => {
       vatAdmin = await E(vats.vatAdmin).createVatAdminService(devices.vatAdmin);
       for (const [name, root] of Object.entries(vats)) {
         if (name !== 'vatAdmin') {
-          vatData.set(name, { root });
+          vatRecords.set(name, { root });
         }
       }
       for (const [name, device] of Object.entries(devices)) {
@@ -33,78 +48,81 @@ export const buildRootObject = () => {
       }
     },
 
-    getDevice: async deviceName => devicesByName.get(deviceName),
+    getDevice: deviceName => devicesByName.get(deviceName),
 
-    getVatAdmin: async () => vatAdmin,
+    /** @todo Reconcile with packages/vats/tools/bootstrap-chain-reflective.js */
+    getTimer: () => manualTimer,
 
-    getTimer: async () => timer,
+    getVatAdmin: () => vatAdmin,
 
-    getVatRoot: async vatName => {
-      const vat = vatData.get(vatName) || Fail`unknown vat name: ${q(vatName)}`;
-      const { root } = vat;
-      return root;
+    getVatAdminNode: vatName => {
+      const vat =
+        vatRecords.get(vatName) || Fail`unknown vat name: ${q(vatName)}`;
+      const { adminNode } = /** @type {DynamicVatRecord} */ (vat);
+      return adminNode;
     },
 
-    createVat: async (
-      { name, bundleCapName, vatParameters = {} },
-      options = {},
-    ) => {
-      const bcap = await E(vatAdmin).getNamedBundleCap(bundleCapName);
-      const vatOptions = { ...options, vatParameters };
-      const { adminNode, root } = await E(vatAdmin).createVat(bcap, vatOptions);
-      vatData.set(name, { adminNode, root });
+    getVatRoot: vatName => {
+      const vat =
+        vatRecords.get(vatName) || Fail`unknown vat name: ${q(vatName)}`;
+      const { root } = vat;
       return root;
     },
 
-    upgradeVat: async ({ name, bundleCapName, vatParameters = {} }) => {
-      const vat = vatData.get(name) || Fail`unknown vat name: ${q(name)}`;
-      const bcap = await E(vatAdmin).getNamedBundleCap(bundleCapName);
-      const options = { vatParameters };
-      const incarnationNumber = await E(vat.adminNode).upgrade(bcap, options);
-      vat.incarnationNumber = incarnationNumber;
-      return incarnationNumber;
-    },
-
     /**
-     * Derives a remotable from an object by mapping each object property into a method that returns the value.
-     *
-     * @param {string} label
-     * @param {Record<string, any>} returnValues
+     * @todo Reconcile with packages/vats/tools/bootstrap-chain-reflective.js
+     * @param {object} details
+     * @param {string} details.name name by which the new vat can be referenced
+     * @param {string} [details.bundleCapName] defaults to name
+     * @param {Record<string, unknown>} [details.vatParameters]
+     * @param {{ vatParameters?: object } & Record<string, unknown>} [vatOptions] for specifying more than vatParameters
+     * @returns {Promise<DynamicVatRecord['root']>} root object of the new vat
      */
-    makeRemotable: (label, returnValues) => {
-      const callLogs = [];
-      const makeGetterFunction = (value, name) => {
-        const getValue = (...args) => {
-          callLogs.push([name, ...args]);
-          return value;
-        };
-        return getValue;
-      };
-      // `objectMap` hardens its result, but...
-      const methods = objectMap(returnValues, makeGetterFunction);
-      // ... `Far` requires its methods argument not to be hardened.
-      const remotable = Far(label, { ...methods });
-      callLogsByRemotable.set(remotable, callLogs);
-      return remotable;
-    },
-
-    makePromiseKit: () => {
-      const { promise, ...resolverMethods } = makePromiseKit();
-      const resolver = Far('resolver', resolverMethods);
-      return harden({ promise, resolver });
+    createVat: async (
+      { name, bundleCapName = name, vatParameters = undefined },
+      vatOptions = {},
+    ) => {
+      if (Object.hasOwn(vatOptions, 'vatParameters') && vatParameters) {
+        Fail`Conflicting specification of vatParameters`;
+      }
+      const bundleCap = await E(vatAdmin).getNamedBundleCap(bundleCapName);
+      const { root, adminNode } = await E(vatAdmin).createVat(bundleCap, {
+        vatParameters: vatParameters || {},
+        ...vatOptions,
+      });
+      vatRecords.set(name, { root, adminNode, bundleCap });
+      return root;
     },
 
     /**
-     * Returns a copy of a remotable's logs.
-     *
-     * @param {object} remotable
+     * @todo Reconcile with packages/vats/tools/bootstrap-chain-reflective.js
+     * @param {object} details
+     * @param {string} details.name name of the vat to upgrade
+     * @param {string} [details.bundleCapName] defaults to the current vat bundle
+     * @param {Record<string, unknown>} [details.vatParameters]
+     * @param {{ vatParameters?: object } & Record<string, unknown>} [vatOptions] for specifying more than vatParameters
+     * @returns {Promise<{ incarnationNumber: number }>} the resulting incarnation number
      */
-    getLogForRemotable: remotable => {
-      const logs =
-        callLogsByRemotable.get(remotable) ||
-        Fail`logs not found for ${q(remotable)}`;
-      // Return a copy so that the original remains mutable.
-      return harden([...logs]);
+    upgradeVat: async (
+      { name, bundleCapName = undefined, vatParameters = undefined },
+      vatOptions = {},
+    ) => {
+      if (Object.hasOwn(vatOptions, 'vatParameters') && vatParameters) {
+        Fail`Conflicting specification of vatParameters`;
+      }
+      const vatRecord =
+        /** @type {DynamicVatRecord} */ (vatRecords.get(name)) ||
+        Fail`unknown vat name: ${q(name)}`;
+      const bundleCap = await (bundleCapName
+        ? E(vatAdmin).getNamedBundleCap(bundleCapName)
+        : vatRecord.bundleCap);
+      const options = { vatParameters: vatParameters || {}, ...vatOptions };
+      const { incarnationNumber } = await E(vatRecord.adminNode).upgrade(
+        bundleCap,
+        options,
+      );
+      vatRecord.incarnationNumber = incarnationNumber;
+      return { incarnationNumber };
     },
 
     awaitVatObject: async (presence, path = []) => {

package/tools/vat-puppet.js

@@ -7,6 +7,8 @@ import { Fail, q } from '@endo/errors';
 import { Far, E } from '@endo/far';
 import { makePromiseKit } from '@endo/promise-kit';
 import { objectMap } from '@agoric/internal';
+import { M } from '@agoric/store';
+import { prepareExoClass, watchPromise } from '@agoric/vat-data';
 
 /**
  * @callback Die
@@ -14,15 +16,61 @@ import { objectMap } from '@agoric/internal';
  * @param {[target: unknown, method: string, ...args: unknown[]]} [finalSend]
  */
 
+/**
+ * @callback SetInStore
+ * @param {string} key
+ * @param {unknown} value
+ * @param {{ mode?: 'init' | 'replace' | 'replaceOrInit' }} [options]
+ */
+
 /**
  * @typedef {Array<[name: string, ...args: unknown[]]>} CallLog
  */
 
+const PromiseWatcherI = M.interface('PromiseWatcher', {
+  onFulfilled: M.call(M.any()).returns(),
+  onRejected: M.call(M.any()).returns(),
+  getResult: M.call().returns(
+    M.or(['unsettled'], [M.or('fulfilled', 'rejected'), M.any()]),
+  ),
+});
+/** @param {unknown} [remoteTarget] */
+const initPromiseWatcher = remoteTarget =>
+  harden({ remoteTarget, result: ['unsettled'] });
+const promiseWatcherMethods = {
+  onFulfilled(value) {
+    this.state.result = harden(['fulfilled', value]);
+    if (!this.state.remoteTarget) return;
+    void E(this.state.remoteTarget).onFulfilled(value);
+  },
+  onRejected(value) {
+    this.state.result = harden(['rejected', value]);
+    if (!this.state.remoteTarget) return;
+    void E(this.state.remoteTarget).onRejected(value);
+  },
+  getResult() {
+    return this.state.result;
+  },
+};
+
 /**
  * @param {import('@agoric/swingset-vat').VatPowers} vatPowers
  * @param {import('@agoric/vat-data').Baggage} baggage
+ * @param {unknown} [vatParameters]
  */
-export const makeReflectionMethods = (vatPowers, baggage) => {
+export const makeReflectionMethods = (vatPowers, baggage, vatParameters) => {
+  // Avoid a @agoric/swingset-vat -> @agoric/zone -> @agoric/swingset-vat
+  // dependency cycle.
+  // const zone = makeDurableZone(baggage);
+  // const makePromiseWatcher = zone.exoClass(...);
+  const makePromiseWatcher = prepareExoClass(
+    baggage,
+    'PromiseWatcher',
+    PromiseWatcherI,
+    initPromiseWatcher,
+    promiseWatcherMethods,
+  );
+
   let baggageHoldCount = 0;
   /** @type {Map<object, CallLog>} */
   const callLogsByRemotable = new Map();
@@ -52,6 +100,8 @@ export const makeReflectionMethods = (vatPowers, baggage) => {
       if (finalSend) send(...finalSend);
     },
 
+    getVatParameters: () => vatParameters,
+
     holdInBaggage: (...values) => {
       for (const value of values) {
         baggage.init(`held-${baggageHoldCount}`, value);
@@ -62,6 +112,25 @@ export const makeReflectionMethods = (vatPowers, baggage) => {
 
     holdInHeap: (...values) => heldInHeap.push(...values),
 
+    /** @type {SetInStore} */
+    setInBaggage: (key, value, { mode = 'replaceOrInit' } = {}) => {
+      const exists = baggage.has(key);
+      if (mode === 'init' || (mode === 'replaceOrInit' && !exists)) {
+        baggage.init(key, value);
+      } else if (mode === 'replace' || (mode === 'replaceOrInit' && exists)) {
+        baggage.set(key, value);
+      } else {
+        Fail`unknown mode ${q(mode)}`;
+      }
+    },
+
+    getFromBaggage: key => baggage.get(key),
+
+    callFromBaggage: (key, methodName, ...args) => {
+      const obj = baggage.get(key);
+      void E(obj)[methodName](...args);
+    },
+
     makePromiseKit: () => {
       const { promise, ...resolverMethods } = makePromiseKit();
       void promise.catch(() => {});
@@ -69,6 +138,8 @@ export const makeReflectionMethods = (vatPowers, baggage) => {
       return harden({ promise, resolver });
     },
 
+    makeSettledPromise: settlement => Promise.resolve(settlement),
+
     makeUnsettledPromise() {
       const { promise } = makePromiseKit();
       void promise.catch(() => {});
@@ -76,17 +147,18 @@ export const makeReflectionMethods = (vatPowers, baggage) => {
     },
 
     /**
-     * Returns a remotable with methods that return provided values. Invocations
-     * of those methods and their arguments are captured for later retrieval by
-     * `getCallLogForRemotable`.
+     * Return a remotable with a method for each property of an optional object
+     * that returns the corresponding property value. Invocations of those
+     * methods and their arguments are captured for later retrieval by
+     * `getLogForRemotable`.
      *
      * @param {string} [label]
-     * @param {Record<string, any>} [fields]
+     * @param {Record<string, any>} [methodReturnValues]
      */
-    makeRemotable: (label = 'Remotable', fields = {}) => {
+    makeRemotable: (label = 'Remotable', methodReturnValues = {}) => {
       /** @type {CallLog} */
       const callLog = [];
-      const methods = objectMap(fields, (value, name) =>
+      const methods = objectMap(methodReturnValues, (value, name) =>
         makeSpy(value, name, callLog),
       );
       const remotable = Far(label, { ...methods });
@@ -95,17 +167,56 @@ export const makeReflectionMethods = (vatPowers, baggage) => {
     },
 
     /**
+     * Return a copy of a remotable's call log.
+     *
      * @param {object} remotable
      * @returns {CallLog}
      */
-    getCallLogForRemotable: remotable =>
-      callLogsByRemotable.get(remotable) ||
-      Fail`unknown remotable ${q(remotable)}`,
+    getLogForRemotable: remotable => {
+      const callLog =
+        callLogsByRemotable.get(remotable) ||
+        Fail`unknown remotable ${q(remotable)}`;
+      // Return an immutable copy of the mutable original.
+      return harden([...callLog]);
+    },
+
+    sendOnly: (target, methodName, ...args) => {
+      void E(target)[methodName](...args);
+    },
+
+    throw: message => {
+      throw Error(message);
+    },
+
+    watchSettledPromiseByProxy: (settlement, watcher, ...args) => {
+      const watcherProxy = makePromiseWatcher(watcher);
+      watchPromise(Promise.resolve(settlement), watcherProxy, ...args);
+    },
   };
 };
 harden(makeReflectionMethods);
 
-export function buildRootObject(vatPowers, _vatParameters, baggage) {
-  const methods = makeReflectionMethods(vatPowers, baggage);
-  return Far('root', methods);
+export function buildRootObject(vatPowers, vatParameters, baggage) {
+  const methods = makeReflectionMethods(vatPowers, baggage, vatParameters);
+  const rootObject = Far('root', methods);
+
+  // Invoke specified methods of the new root object *before* returning,
+  // supporting use of previous results as top-level arguments by interpreting
+  // registered symbols with decimal-integer descriptions as references into an
+  // array of previous results.
+  const { initialCalls = [] } = vatParameters || {};
+  const results = [];
+  const decimalIntPatt = /^-?(?:0|[1-9][0-9]*)$/;
+  const translateArg = arg => {
+    if (typeof arg !== 'symbol' || !Symbol.keyFor(arg)) return arg;
+    if (!arg.description?.match(decimalIntPatt)) return arg;
+    return results.at(Number(arg.description));
+  };
+  for (const [methodName, ...args] of initialCalls) {
+    const translatedArgs = args.map(translateArg);
+    const result = rootObject[methodName](...translatedArgs);
+    results.push(result);
+  }
+
+  return rootObject;
 }