@agoric/swingset-vat 0.33.0-u20.0 → 0.33.0-u21.0

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@agoric/swingset-vat",
-  "version": "0.33.0-u20.0",
+  "version": "0.33.0-u21.0",
   "description": "Vat/Container Launcher",
   "type": "module",
   "main": "src/index.js",
   "engines": {
-    "node": "^18.12 || ^20.9"
+    "node": "^20.9 || ^22.11"
   },
   "bin": {
     "vat": "bin/vat"
@@ -13,29 +13,31 @@
   "scripts": {
     "build": "exit 0",
     "test": "ava",
+    "test:c8": "c8 --all $C8_OPTIONS ava",
     "test:xs": "SWINGSET_WORKER_TYPE=xs-worker ava",
     "test:xs-worker": "ava test/workers -m 'xsnap vat manager'",
     "lint-fix": "yarn lint:eslint --fix",
-    "lint": "run-s --continue-on-error lint:*",
-    "lint:types": "tsc",
-    "lint:eslint": "eslint ."
+    "lint": "yarn run -T run-s --continue-on-error 'lint:*'",
+    "lint:types": "yarn run -T tsc",
+    "lint:eslint": "yarn run -T eslint ."
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.9",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/microtime": "^2.1.0",
     "@types/tmp": "^0.2.0",
-    "@types/yargs-parser": "^21.0.0"
+    "@types/yargs-parser": "^21.0.0",
+    "ava": "^5.3.0"
   },
   "dependencies": {
-    "@agoric/internal": "^0.4.0-u20.0",
-    "@agoric/kmarshal": "^0.1.1-u20.0",
-    "@agoric/store": "^0.9.3-u20.0",
-    "@agoric/swing-store": "^0.10.0-u20.0",
-    "@agoric/swingset-liveslots": "^0.10.3-u20.0",
-    "@agoric/swingset-xsnap-supervisor": "^0.10.3-u20.0",
-    "@agoric/time": "^0.3.3-u20.0",
-    "@agoric/vat-data": "^0.5.3-u20.0",
-    "@agoric/xsnap-lockdown": "^0.14.1-u20.0",
+    "@agoric/internal": "workspace:*",
+    "@agoric/kmarshal": "workspace:*",
+    "@agoric/store": "workspace:*",
+    "@agoric/swing-store": "workspace:*",
+    "@agoric/swingset-liveslots": "workspace:*",
+    "@agoric/swingset-xsnap-supervisor": "workspace:*",
+    "@agoric/time": "workspace:*",
+    "@agoric/vat-data": "workspace:*",
+    "@agoric/xsnap-lockdown": "workspace:*",
     "@endo/base64": "^1.0.9",
     "@endo/bundle-source": "^4.0.0",
     "@endo/captp": "^4.4.5",
@@ -56,7 +58,7 @@
     "@endo/zip": "^1.0.9",
     "ansi-styles": "^6.2.1",
     "anylogger": "^0.21.0",
-    "better-sqlite3": "^9.1.1",
+    "better-sqlite3": "^10.1.0",
     "import-meta-resolve": "^4.1.0",
     "microtime": "^3.1.0",
     "semver": "^6.3.0",
@@ -64,7 +66,7 @@
     "yargs-parser": "^21.1.1"
   },
   "peerDependencies": {
-    "@agoric/xsnap": "^0.14.2",
+    "@agoric/xsnap": "workspace:*",
     "ava": "^5.3.0"
   },
   "files": [
@@ -100,7 +102,7 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 76.25
+    "atLeast": 76.47
   },
-  "gitHead": "8e4207fa19dabf76c1f91f8779b5b5b93570ecea"
+  "gitHead": "e4dd46857133403d584bcf822a81817b355532f9"
 }

package/src/controller/controller.js

@@ -425,8 +425,12 @@ export async function makeSwingsetController(
         return kernel.shutdown();
       },
 
-      reapAllVats() {
-        kernel.reapAllVats();
+      reapAllVats(previousVatPos) {
+        return kernel.reapAllVats(previousVatPos);
+      },
+
+      async snapshotAllVats() {
+        return kernel.snapshotAllVats();
       },
 
       changeKernelOptions(options) {

package/src/controller/upgradeSwingset.js

@@ -285,11 +285,9 @@ export const upgradeSwingset = kernelStorage => {
 
     const buggyKPIDs = []; // [kpid, vatID]
     for (const vatID of allVatIDs) {
-      const prefix = `${vatID}.c.`;
-      const len = prefix.length;
       const ckpPrefix = `${vatID}.c.kp`;
-      for (const key of enumeratePrefixedKeys(kvStore, ckpPrefix)) {
-        const kpid = key.slice(len);
+      for (const { suffix } of enumeratePrefixedKeys(kvStore, ckpPrefix)) {
+        const kpid = `kp${suffix}`;
         if (isSettled(kpid)) {
           const n = notifies.get(kpid);
           if (!n || !n.includes(vatID)) {

package/src/devices/bridge/device-bridge.js

@@ -62,3 +62,5 @@ export function buildRootDeviceNode(tools) {
     },
   });
 }
+
+/** @typedef {import('../../types-external.js').Device<ReturnType<typeof buildRootDeviceNode>>} BridgeDevice */

package/src/devices/timer/device-timer.js

@@ -86,6 +86,7 @@ function makeTimerMap(state = undefined) {
     return copyState(schedule);
   }
 
+  /** @param {bigint} time */
   function eventsFor(time) {
     assert.typeof(time, 'bigint');
     for (let i = 0; i < schedule.length && schedule[i].time <= time; i += 1) {
@@ -101,17 +102,29 @@ function makeTimerMap(state = undefined) {
   // There's some question as to whether it's important to invoke the handlers
   // in the order of their deadlines. If so, we should probably ensure that the
   // recorded deadlines don't have finer granularity than the turns.
-  function add(time, handler, repeater = undefined) {
+  /**
+   *
+   * @param {bigint} time
+   * @param {Waker} handler
+   * @param {number} [index]
+   * @returns {bigint}
+   */
+  function add(time, handler, index = undefined) {
     assert.typeof(time, 'bigint');
+    /** @type {IndexedHandler} */
     const handlerRecord =
-      typeof repeater === 'number' ? { handler, index: repeater } : { handler };
+      typeof index === 'number' ? { handler, index } : { handler };
     const { handlers: records } = eventsFor(time);
     records.push(handlerRecord);
     schedule.sort((a, b) => Number(a.time - b.time));
     return time;
   }
 
-  // Remove and return all pairs indexed by numbers up to target
+  /**
+   * Remove and return all pairs indexed by numbers up to target
+   *
+   * @param {bigint} target
+   */
   function removeEventsThrough(target) {
     assert.typeof(target, 'bigint');
     const returnValues = [];
@@ -132,33 +145,29 @@ function makeTimerMap(state = undefined) {
   }
 
   // We don't expect this to be called often, so we don't optimize for it.
+  /**
+   *
+   * @param {Waker} targetHandler
+   * @returns {bigint[]} times that have been removed (may contain duplicates)
+   */
   function remove(targetHandler) {
+    /** @type {bigint[]} */
     const droppedTimes = [];
     let i = 0;
     while (i < schedule.length) {
       const { time, handlers } = schedule[i];
-      if (handlers.length === 1) {
-        if (handlers[0].handler === targetHandler) {
-          schedule.splice(i, 1);
+      // Nothing prevents a particular handler from appearing more than once
+      for (let j = handlers.length - 1; j >= 0; j -= 1) {
+        if (handlers[j].handler === targetHandler) {
+          handlers.splice(j, 1);
           droppedTimes.push(time);
-        } else {
-          i += 1;
         }
+      }
+      if (handlers.length === 0) {
+        // Splice out this element, preserving `i` so we visit any successor.
+        schedule.splice(i, 1);
       } else {
-        // Nothing prevents a particular handler from appearing more than once
-        for (const { handler } of handlers) {
-          // @ts-expect-error xxx Waker vs IndexedHandler
-          if (handler === targetHandler && handlers.indexOf(handler) !== -1) {
-            // @ts-expect-error xxx Waker vs IndexedHandler
-            handlers.splice(handlers.indexOf(handler), 1);
-            droppedTimes.push(time);
-          }
-        }
-        if (handlers.length === 0) {
-          schedule.splice(i, 1);
-        } else {
-          i += 1;
-        }
+        i += 1;
       }
     }
     return droppedTimes;
@@ -223,6 +232,7 @@ export function buildRootDeviceNode(tools) {
   // The latest time poll() was called. This might be a block height or it
   // might be a time from Date.now(). The current time is not reflected back
   // to the user.
+  /** @type {bigint} */
   let lastPolled = restart ? restart.lastPolled : 0n;
   let nextRepeater = restart ? restart.nextRepeater : 0;
 
@@ -276,6 +286,10 @@ export function buildRootDeviceNode(tools) {
       saveState();
       return baseTime;
     },
+    /**
+     * @param {Waker} handler
+     * @returns {bigint[]} times that have been removed (may contain duplicates)
+     */
     removeWakeup(handler) {
       const times = deadlines.remove(handler);
       saveState();
@@ -303,6 +317,10 @@ export function buildRootDeviceNode(tools) {
       saveState();
       return index;
     },
+    /**
+     * @param {number} index
+     * @param {Waker} handler
+     */
     schedule(index, handler) {
       const nextTime = nextScheduleTime(index, repeaters, lastPolled);
       deadlines.add(nextTime, handler, index);
@@ -311,6 +329,7 @@ export function buildRootDeviceNode(tools) {
     },
   });
 }
+/** @typedef {import('../../types-external.js').Device<ReturnType<typeof buildRootDeviceNode>>} TimerDevice */
 
 // exported for testing. Only buildRootDeviceNode is intended for production
 // use.

package/src/kernel/kernel.js

@@ -1946,15 +1946,63 @@ export default function buildKernel(
     }
   }
 
-  function reapAllVats() {
+  /** @returns {Generator<VatID>} */
+  function* getAllVatIds() {
     for (const [_, vatID] of kernelKeeper.getStaticVats()) {
-      kernelKeeper.scheduleReap(vatID);
+      yield vatID;
     }
     for (const vatID of kernelKeeper.getDynamicVats()) {
-      kernelKeeper.scheduleReap(vatID);
+      yield vatID;
     }
   }
 
+  function* getAllVatPosEntries() {
+    for (const vatID of getAllVatIds()) {
+      const vatKeeper = kernelKeeper.provideVatKeeper(vatID);
+      yield /** @type {const} */ ([
+        vatID,
+        vatKeeper.getTranscriptEndPosition(),
+      ]);
+    }
+  }
+
+  function reapAllVats(previousVatPos = {}) {
+    /** @type {Record<string, number>} */
+    const currentVatPos = {};
+
+    for (const [vatID, endPos] of getAllVatPosEntries()) {
+      const vatUsesTranscript = endPos !== 0;
+      if (!vatUsesTranscript) {
+        // The comms vat is a little special. It doesn't use a transcript,
+        // doesn't implement BOYD, and is created with a never reap threshold.
+        //
+        // Here we conflate a vat that doesn't use a transcript with a vat
+        // that cannot reap. We do not bother checking the vat options because
+        // in tests we would actually like to force reap normal vats that may
+        // have been configured with a never threshold.
+        continue;
+      } else if ((previousVatPos[vatID] ?? 0) < endPos) {
+        kernelKeeper.scheduleReap(vatID);
+        // We just added one delivery
+        currentVatPos[vatID] = endPos + 1;
+      } else {
+        currentVatPos[vatID] = endPos;
+      }
+    }
+
+    return harden(currentVatPos);
+  }
+
+  async function snapshotAllVats() {
+    const snapshottedVats = [];
+    await null;
+    for (const vatID of getAllVatIds()) {
+      const snapshotted = await vatWarehouse.maybeSaveSnapshot(vatID, 2);
+      if (snapshotted) snapshottedVats.push(vatID);
+    }
+    return harden(snapshottedVats);
+  }
+
   async function step() {
     if (kernelPanic) {
       throw kernelPanic;
@@ -2159,6 +2207,7 @@ export default function buildKernel(
     run,
     shutdown,
     reapAllVats,
+    snapshotAllVats,
     changeKernelOptions,
 
     // the rest are for testing and debugging

package/src/kernel/state/deviceKeeper.js

@@ -189,11 +189,12 @@ export function makeDeviceKeeper(kvStore, deviceID, tools) {
     /** @type {Array<[string, string, string]>} */
     const res = [];
     const prefix = `${deviceID}.c.`;
-    for (const k of enumeratePrefixedKeys(kvStore, prefix)) {
-      const slot = k.slice(prefix.length);
+    const prefixedKeys = enumeratePrefixedKeys(kvStore, prefix);
+
+    for (const { key, suffix: slot } of prefixedKeys) {
       if (!slot.startsWith('k')) {
         const devSlot = slot;
-        const kernelSlot = kvStore.get(k);
+        const kernelSlot = kvStore.get(key);
         res.push([kernelSlot, deviceID, devSlot]);
       }
     }

package/src/kernel/state/kernelKeeper.js

@@ -212,9 +212,8 @@ function insistMeterID(m) {
 export const getAllStaticVats = kvStore => {
   const result = [];
   const prefix = 'vat.name.';
-  for (const k of enumeratePrefixedKeys(kvStore, prefix)) {
-    const vatID = kvStore.get(k) || Fail`getNextKey ensures get`;
-    const name = k.slice(prefix.length);
+  for (const { key, suffix: name } of enumeratePrefixedKeys(kvStore, prefix)) {
+    const vatID = kvStore.get(key) || Fail`getNextKey ensures get`;
     result.push([name, vatID]);
   }
   return result;
@@ -718,17 +717,22 @@ export default function makeKernelKeeper(
     // We iterate through all ephemeral and virtual entries so the kernel
     // can ensure that they are abandoned by a vat being upgraded.
     const prefix = `${vatID}.c.`;
-    const ephStart = `${prefix}o+`;
-    const durStart = `${prefix}o+d`;
-    const virStart = `${prefix}o+v`;
+    const ephStart = `o+`;
+    const durStart = `o+d`;
+    const virStart = `o+v`;
     /** @type {[string, string?][]} */
     const ranges = [[ephStart, durStart], [virStart]];
     for (const range of ranges) {
-      for (const k of enumeratePrefixedKeys(kvStore, ...range)) {
-        const vref = k.slice(prefix.length);
+      const rangeSuffix = range[0];
+      const args = /** @type {typeof ranges[0]} */ (
+        /** @type {unknown} */ (range.map(s => `${prefix}${s}`))
+      );
+      const prefixedKeys = enumeratePrefixedKeys(kvStore, ...args);
+      for (const { key, suffix } of prefixedKeys) {
+        const vref = `${rangeSuffix}${suffix}`;
         // exclude the root object, which is replaced by upgrade
         if (vref !== 'o+0') {
-          const kref = kvStore.get(k);
+          const kref = kvStore.get(key);
           assert.typeof(kref, 'string');
           yield { kref, vref };
         }
@@ -1072,7 +1076,7 @@ export default function makeKernelKeeper(
 
     // first, scan for exported objects, which must be orphaned
     remaining = budget.exports ?? budget.default;
-    for (const k of enumeratePrefixedKeys(kvStore, exportPrefix)) {
+    for (const { key } of enumeratePrefixedKeys(kvStore, exportPrefix)) {
       // The void for an object exported by a vat will always be of the form
       // `o+NN`.  The '+' means that the vat exported the object (rather than
       // importing it) and therefore the object is owned by (i.e., within) the
@@ -1080,9 +1084,7 @@ export default function makeKernelKeeper(
       // begin with `vMM.c.o+`.  In addition to deleting the c-list entry, we
       // must also delete the corresponding kernel owner entry for the object,
       // since the object will no longer be accessible.
-      const vref = stripPrefix(clistPrefix, k);
-      assert(vref.startsWith('o+'), vref);
-      const kref = kvStore.get(k);
+      const kref = kvStore.get(key);
       // note: adds to maybeFreeKrefs, deletes c-list and .owner
       orphanKernelObject(kref, vatID);
       work.exports += 1;
@@ -1094,11 +1096,14 @@ export default function makeKernelKeeper(
 
     // then scan for imported objects, which must be decrefed
     remaining = budget.imports ?? budget.default;
-    for (const k of enumeratePrefixedKeys(kvStore, importPrefix)) {
+    for (const { key, suffix } of enumeratePrefixedKeys(
+      kvStore,
+      importPrefix,
+    )) {
       // abandoned imports: delete the clist entry as if the vat did a
       // drop+retire
-      const kref = kvStore.get(k) || Fail`getNextKey ensures get`;
-      const vref = stripPrefix(clistPrefix, k);
+      const kref = kvStore.get(key) || Fail`getNextKey ensures get`;
+      const vref = `o-${suffix}`;
       undertaker.deleteCListEntry(kref, vref);
       // that will also delete both db keys
       work.imports += 1;
@@ -1113,9 +1118,12 @@ export default function makeKernelKeeper(
     // kpids are still present in the dead vat's c-list. Clean those
     // up now.
     remaining = budget.promises ?? budget.default;
-    for (const k of enumeratePrefixedKeys(kvStore, promisePrefix)) {
-      const kref = kvStore.get(k) || Fail`getNextKey ensures get`;
-      const vref = stripPrefix(clistPrefix, k);
+    for (const { key, suffix } of enumeratePrefixedKeys(
+      kvStore,
+      promisePrefix,
+    )) {
+      const kref = kvStore.get(key) || Fail`getNextKey ensures get`;
+      const vref = `p${suffix}`;
       undertaker.deleteCListEntry(kref, vref);
       // that will also delete both db keys
       work.promises += 1;
@@ -1127,8 +1135,8 @@ export default function makeKernelKeeper(
 
     // now loop back through everything and delete it all
     remaining = budget.kv ?? budget.default;
-    for (const k of enumeratePrefixedKeys(kvStore, `${vatID}.`)) {
-      kvStore.delete(k);
+    for (const { key } of enumeratePrefixedKeys(kvStore, `${vatID}.`)) {
+      kvStore.delete(key);
       work.kv += 1;
       remaining -= 1;
       if (remaining <= 0) {
@@ -1167,11 +1175,11 @@ export default function makeKernelKeeper(
       kvStore.set(DYNAMIC_IDS_KEY, JSON.stringify(newDynamicVatIDs));
     } else {
       kdebug(`removing static vat ${vatID}`);
-      for (const k of enumeratePrefixedKeys(kvStore, 'vat.name.')) {
-        if (kvStore.get(k) === vatID) {
-          kvStore.delete(k);
+      const prefixedKeys = enumeratePrefixedKeys(kvStore, 'vat.name.');
+      for (const { key, suffix: name } of prefixedKeys) {
+        if (kvStore.get(key) === vatID) {
+          kvStore.delete(key);
           const VAT_NAMES_KEY = 'vat.names';
-          const name = k.slice('vat.name.'.length);
           const oldStaticVatNames = JSON.parse(getRequired(VAT_NAMES_KEY));
           const newStaticVatNames = oldStaticVatNames.filter(v => v !== name);
           kvStore.set(VAT_NAMES_KEY, JSON.stringify(newStaticVatNames));
@@ -1240,7 +1248,7 @@ export default function makeKernelKeeper(
   function* enumeratePromisesByDecider(vatID) {
     insistVatID(vatID);
     const promisePrefix = `${vatID}.c.p`;
-    for (const k of enumeratePrefixedKeys(kvStore, promisePrefix)) {
+    for (const { key } of enumeratePrefixedKeys(kvStore, promisePrefix)) {
       // The vpid for a promise imported or exported by a vat (and thus
       // potentially a promise for which the vat *might* be the decider) will
       // always be of the form `p+NN` or `p-NN`.  The corresponding vpid->kpid
@@ -1250,7 +1258,7 @@ export default function makeKernelKeeper(
       // whether the vat is the decider or not.  If it is, we add the promise
       // to the list of promises that must be rejected because the dead vat
       // will never be able to act upon them.
-      const kpid = getRequired(k);
+      const kpid = getRequired(key);
       const p = getKernelPromise(kpid);
       if (p.state === 'unresolved' && p.decider === vatID) {
         yield [kpid, p];
@@ -1449,9 +1457,9 @@ export default function makeKernelKeeper(
 
   function getDevices() {
     const result = [];
-    for (const k of enumeratePrefixedKeys(kvStore, 'device.name.')) {
-      const name = k.slice(12);
-      const deviceID = kvStore.get(k) || Fail`getNextKey ensures get`;
+    const prefixedKeys = enumeratePrefixedKeys(kvStore, 'device.name.');
+    for (const { key, suffix: name } of prefixedKeys) {
+      const deviceID = kvStore.get(key) || Fail`getNextKey ensures get`;
       result.push([name, deviceID]);
     }
     return result;

package/src/kernel/state/storageHelper.js

@@ -13,7 +13,8 @@ import { Fail } from '@endo/errors';
  * @param {KVStore} kvStore
  * @param {string} prefix
  * @param {string} [exclusiveEnd]
- * @yields {string} the next key with the prefix that is not >= exclusiveEnd
+ * @yields {{key: string; suffix: string}} the next `key` with the prefix that is not >= exclusiveEnd
+ * and the `suffix` which is obtained by stripping the supplied prefix from the key
  */
 export function* enumeratePrefixedKeys(kvStore, prefix, exclusiveEnd) {
   /** @type {string | undefined} */
@@ -26,7 +27,7 @@ export function* enumeratePrefixedKeys(kvStore, prefix, exclusiveEnd) {
     if (exclusiveEnd && key >= exclusiveEnd) {
       break;
     }
-    yield key;
+    yield { key, suffix: key.slice(prefix.length) };
   }
 }
 harden(enumeratePrefixedKeys);

package/src/kernel/state/vatKeeper.js

@@ -761,11 +761,13 @@ export function makeVatKeeper(
   function dumpState() {
     const res = [];
     const prefix = `${vatID}.c.`;
-    for (const k of enumeratePrefixedKeys(kvStore, prefix)) {
-      const slot = k.slice(prefix.length);
+    for (const { key, suffix: slot } of enumeratePrefixedKeys(
+      kvStore,
+      prefix,
+    )) {
       if (!slot.startsWith('k')) {
         const vatSlot = slot;
-        const kernelSlot = kvStore.get(k) || Fail`getNextKey ensures get`;
+        const kernelSlot = kvStore.get(key) || Fail`getNextKey ensures get`;
         /** @type { [string, string, string] } */
         const item = [kernelSlot, vatID, vatSlot];
         res.push(item);

package/src/kernel/vat-warehouse.js

@@ -566,18 +566,20 @@ export function makeVatWarehouse({
 
   /**
    * Save a heap snapshot for the given vatID, if the snapshotInterval
-   * is satisified
+   * is satisfied or a lower explicit delivery count has been reached.
    *
    * @param {VatID} vatID
+   * @param {number} [minDeliveryCount]
    */
-  async function maybeSaveSnapshot(vatID) {
-    const recreate = true; // PANIC in the failure case
-    const { manager } = await ensureVatOnline(vatID, recreate);
-    if (!manager.makeSnapshot) {
-      return false; // worker cannot make snapshots
+  async function maybeSaveSnapshot(vatID, minDeliveryCount = snapshotInterval) {
+    kernelKeeper.vatIsAlive(vatID) || Fail`${q(vatID)}: not alive`;
+    const vatKeeper = kernelKeeper.provideVatKeeper(vatID);
+    const vatOptions = vatKeeper.getOptions();
+
+    if (!vatOptions.useTranscript) {
+      return false;
     }
 
-    const vatKeeper = kernelKeeper.provideVatKeeper(vatID);
     let reason;
 
     const hasSnapshot = !!vatKeeper.getSnapshotInfo();
@@ -586,15 +588,21 @@ export function makeVatWarehouse({
     if (!hasSnapshot && deliveriesInSpan >= snapshotInitial) {
       // begin snapshot after 'snapshotInitial' deliveries in an incarnation
       reason = { snapshotInitial };
-    } else if (deliveriesInSpan >= snapshotInterval) {
+    } else if (deliveriesInSpan >= minDeliveryCount) {
       // begin snapshot after 'snapshotInterval' deliveries in a span
-      reason = { snapshotInterval };
+      reason = { snapshotInterval: minDeliveryCount };
     }
     // console.log('maybeSaveSnapshot: reason:', reason);
     if (!reason) {
       return false; // not time to make a snapshot
     }
 
+    const recreate = true; // PANIC in the failure case
+    const { manager } = await ensureVatOnline(vatID, recreate);
+    if (!manager.makeSnapshot) {
+      return false; // worker cannot make snapshots
+    }
+
     // always do a bringOutYourDead just before a snapshot, to shake
     // loose as much garbage as we can, and to minimize the GC
     // sensitivity effects of the forced GC that snapshots perform

package/src/lib/capdata.js

@@ -1,24 +1,11 @@
-import { Fail } from '@endo/errors';
+import { krefOf, kunser } from '@agoric/kmarshal';
 import { passStyleOf } from '@endo/far';
-import { kunser, krefOf } from '@agoric/kmarshal';
 
 /**
- * Assert function to ensure that something expected to be a capdata object
- * actually is.  A capdata object should have a .body property that's a string
- * and a .slots property that's an array of strings.
- *
- * @param {any} capdata  The object to be tested
- * @throws {Error} if, upon inspection, the parameter does not satisfy the above
- *   criteria.
- * @returns {asserts capdata is import('@endo/marshal').CapData<string>}
+ * @import {CapData} from '@endo/marshal';
  */
-export function insistCapData(capdata) {
-  typeof capdata.body === 'string' ||
-    Fail`capdata has non-string .body ${capdata.body}`;
-  Array.isArray(capdata.slots) ||
-    Fail`capdata has non-Array slots ${capdata.slots}`;
-  // TODO check that the .slots array elements are actually strings
-}
+
+export { insistCapData } from '@agoric/swingset-liveslots/src/capdata.js';
 
 /**
  * Returns the slot of a presence if the provided capdata is composed

package/src/types-external.js

@@ -12,6 +12,13 @@ export {};
  * includes standard services which user-provided vat code might interact
  * with, like VatAdminService. */
 
+/**
+ * @template T
+ * @typedef {'Device' & { __deviceType__: T }} Device
+ */
+
+/** @typedef {<T>(target: Device<T>) => T} DProxy (approximately) */
+
 /**
  * @typedef {(extraProps?: SlogDurationProps) => void} FinishSlogDuration
  */
@@ -25,12 +32,17 @@ export {};
  * @typedef {'getExport' | 'nestedEvaluate' | 'endoZipBase64'} BundleFormat
  * @typedef { { moduleFormat: 'getExport', source: string, sourceMap?: string } } GetExportBundle
  * @typedef { { moduleFormat: 'nestedEvaluate', source: string, sourceMap?: string } } NestedEvaluateBundle
- * @typedef { { moduleFormat: 'test' } } TestBundle
+ * @typedef { { moduleFormat: 'test', [x: symbol]: Record<PropertyKey, unknown> } } TestBundle
  * @typedef { EndoZipBase64Bundle | GetExportBundle | NestedEvaluateBundle | TestBundle} Bundle
  */
 
 /**
  * @typedef { 'local' | 'node-subprocess' | 'xsnap' | 'xs-worker' } ManagerType
+ *   The type of worker for hosting a vat.
+ *   - **local**: a Compartment in the SwingSet Node.js process
+ *   - **node-subprocess**: a child process using the same Node.js executable
+ *      (`process.execPath`)
+ *   - **xsnap** or **xs-worker**: an {@link @agoric/xsnap! @agoric/xsnap} worker
  */
 
 /**
@@ -390,7 +402,9 @@ export {};
  *
  * @typedef { { vatParameters?: object, upgradeMessage?: string } } VatUpgradeOptions
  * @typedef { { incarnationNumber: number } } VatUpgradeResults
- *
+ */
+
+/**
  * @callback ShutdownWithFailure
  * Called to shut something down because something went wrong, where the reason
  * is supposed to be an Error that describes what went wrong. Some valid
@@ -401,7 +415,9 @@ export {};
  *
  * @param {Error} reason
  * @returns {void}
- *
+ */
+
+/**
  * @typedef {object} VatAdminFacet
  * A powerful object corresponding with a vat
  * that can be used to upgrade it with new code or parameters,
@@ -419,8 +435,9 @@ export {};
  * in which the JS memory space is abandoned. The new image is launched with access to 'baggage'
  * and any durable storage reachable from it, and must fulfill all the obligations of the previous
  * incarnation.
- *
- *
+ */
+
+/**
  * @typedef {{ adminNode: Guarded<VatAdminFacet>, root: object }} CreateVatResults
  *
  * @typedef {object} VatAdminSvc
@@ -429,5 +446,4 @@ export {};
  * @property {(name: string) => ERef<BundleCap>} getNamedBundleCap
  * @property {(name: string) => ERef<BundleID>} getBundleIDByName
  * @property {(bundleCap: BundleCap, options?: DynamicVatOptions) => ERef<CreateVatResults>} createVat
- *
  */

package/src/vats/plugin-manager.js

@@ -7,6 +7,8 @@ import { Far, E } from '@endo/far';
 
 /**
  * @import {ERef} from '@endo/far';
+ * @import {MapStore} from '@agoric/store';
+ * @import {Device, DProxy} from '@agoric/swingset-vat/src/types-external.js';
  */
 
 /** @type {{ onReset: (firstTime: Promise<boolean>) => void}} */
@@ -15,13 +17,6 @@ const DEFAULT_RESETTER = Far('resetter', { onReset: _ => {} });
 /** @type {{ walk: (pluginRootP: any) => any }} */
 const DEFAULT_WALKER = Far('walker', { walk: pluginRootP => pluginRootP });
 
-/**
- * @template T
- * @typedef {'Device' & { __deviceType__: T }} Device
- */
-
-/** @typedef {<T>(target: Device<T>) => T} DProxy (approximately) */
-
 /**
  * @callback LoadPlugin
  * @param {string} specifier

package/src/vats/timer/vat-timer.js

@@ -15,9 +15,11 @@ import { TimeMath } from '@agoric/time';
 
 /**
  * @import {LegacyWeakMap, WeakMapStore} from '@agoric/store';
- * @import {MapStore} from '@agoric/swingset-liveslots';
+ * @import {Baggage, MapStore} from '@agoric/swingset-liveslots';
  * @import {Passable, RemotableObject} from '@endo/pass-style';
  * @import {Key} from '@endo/patterns';
+ * @import {TimerDevice} from '../../devices/timer/device-timer.js';
+ * @import {DProxy} from '../../types-external.js';
  */
 
 // This consumes O(N) RAM only for outstanding promises, via wakeAt(),
@@ -237,9 +239,17 @@ const measureInterval = (start, interval, now) => {
   return { latest, next };
 };
 
+/**
+ * @param {{
+ *   D: DProxy;
+ * }} vatPowers
+ * @param {{}} _vatParameters
+ * @param {Baggage} baggage
+ */
 export const buildRootObject = (vatPowers, _vatParameters, baggage) => {
   const { D } = vatPowers;
 
+  /** @type {TimerDevice} */
   let timerDevice;
   const insistDevice = () => {
     assert(timerDevice, 'TimerService used before createTimerService()');
@@ -455,9 +465,6 @@ export const buildRootObject = (vatPowers, _vatParameters, baggage) => {
     },
   };
 
-  /**
-   * @returns { PromiseEvent }
-   */
   const makePromiseEvent = prepareKind(
     baggage,
     'promiseEvent',
@@ -948,7 +955,7 @@ export const buildRootObject = (vatPowers, _vatParameters, baggage) => {
    * device, but we don't prohibit it from being called again (to
    * replace the device), just in case that's useful someday
    *
-   * @param {unknown} timerNode
+   * @param {TimerDevice} timerNode
    * @returns {TimerService}
    */
   const createTimerService = timerNode => {

package/src/vats/vat-admin/vat-vat-admin.js

@@ -20,7 +20,7 @@ import {
 
 /**
  * @import {VatAdminRootDeviceNode} from '../../devices/vat-admin/device-vat-admin.js';
- * @import {DProxy} from'../plugin-manager.js';
+ * @import {DProxy} from'../../types-external.js';
  * @import {Baggage} from '@agoric/vat-data';
  */
 
@@ -49,7 +49,7 @@ export function buildRootObject(vatPowers, _vatParameters, baggage) {
   const pendingBundles = new Map();
   const pendingUpgrades = new Map(); // upgradeID -> Promise<UpgradeResults>
 
-  /** @type {import('../plugin-manager.js').Device<VatAdminRootDeviceNode>} */
+  /** @type {import('../../types-external.js').Device<VatAdminRootDeviceNode>} */
   let vatAdminDev;
 
   const runningVats = new Map(); // vatID -> [doneP, { resolve, reject }]

package/tools/manual-timer.js

@@ -8,7 +8,7 @@ import { buildRootObject } from '../src/vats/timer/vat-timer.js';
 /**
  * @import {Timestamp} from '@agoric/time'
  * @import {TimerService} from '@agoric/time'
- * @import {Waker} from '../src/devices/timer/device-timer.js'
+ * @import {TimerDevice, Waker} from '../src/devices/timer/device-timer.js'
  *
  * @typedef {object} ManualTimerCallbacks
  * @property {(newTime: bigint, msg?: string) => void} [advanceTo]
@@ -34,7 +34,7 @@ const setup = callbacks => {
     currentWakeup: undefined,
     currentHandler: undefined,
   };
-  const deviceMarker = harden({});
+  const deviceMarker = /** @type {TimerDevice} */ (harden({}));
   const timerDeviceFuncs = harden({
     getLastPolled: () => state.now,
     setWakeup: (when, handler) => {
@@ -54,6 +54,7 @@ const setup = callbacks => {
       state.currentHandler = undefined;
     },
   });
+  /** @type {any} */
   const D = node => {
     assert.equal(node, deviceMarker, 'fake D only supports devices.timer');
     return timerDeviceFuncs;