@agoric/swingset-vat 0.32.3-upgrade-16-dev-b7c2f02.0 → 0.32.3-upgrade-17-dev-3b97a9f.0

package/src/types-external.js

@@ -1,10 +1,10 @@
-/** @import { ERef } from '@endo/far' */
+/** @import { ERef } from '@endo/far'; */
 
 export {};
 
 /**
- * @import {Guarded} from '@endo/exo')
- * @import {Passable, RemotableObject} from '@endo/pass-style')
+ * @import {Guarded} from '@endo/exo';
+ * @import {Passable, RemotableObject} from '@endo/pass-style';
  */
 
 /* This file defines types that part of the external API of swingset. That
@@ -28,14 +28,14 @@ export {};
  */
 
 /**
- * @typedef {{
- *   defaultManagerType?: ManagerType,
- *   defaultReapInterval?: number | 'never',
- *   relaxDurabilityRules?: boolean,
- *   snapshotInitial?: number,
- *   snapshotInterval?: number,
- *   pinBootstrapRoot?: boolean,
- * }} KernelOptions
+ * @typedef {object} KernelOptions
+ * @property {ManagerType} [defaultManagerType]
+ * @property {number | 'never'} [defaultReapGCKrefs]
+ * @property {number | 'never'} [defaultReapInterval]
+ * @property {boolean} [relaxDurabilityRules]
+ * @property {number} [snapshotInitial]
+ * @property {number} [snapshotInterval]
+ * @property {boolean} [pinBootstrapRoot]
  */
 
 /**
@@ -167,6 +167,7 @@ export {};
  *   bundleName: string
  * }} BundleName
  * @typedef {(SourceSpec | BundleSpec | BundleRef | BundleName ) & {
+ *   bundleID?: BundleID,
  *   creationOptions?: Record<string, any>,
  *   parameters?: Record<string, any>,
  * }} SwingSetConfigProperties
@@ -218,19 +219,65 @@ export {};
  */
 
 /**
+ * PolicyInput is used internally within kernel.js, returned by each
+ * message processor, and used to decide which of the host's runPolicy
+ * methods to invoke. The 'details' portion of PolicyInput is passed
+ * as an argument to those methods, so those types are
+ * externally-visible.
+ *
+ * @typedef { { exports: number,
+ *              imports: number,
+ *              kv: number,
+ *              snapshots: number,
+ *              transcripts: number,
+ *            } } CleanupWork
+ *
+ * @typedef { { total: number } & CleanupWork } PolicyInputCleanupCounts
+ * @typedef { { cleanups: PolicyInputCleanupCounts, computrons?: bigint } } PolicyInputCleanupDetails
  * @typedef { { computrons?: bigint } } PolicyInputDetails
+ *
  * @typedef { [tag: 'none', details: PolicyInputDetails ] } PolicyInputNone
  * @typedef { [tag: 'create-vat', details: PolicyInputDetails  ]} PolicyInputCreateVat
  * @typedef { [tag: 'crank', details: PolicyInputDetails ] } PolicyInputCrankComplete
  * @typedef { [tag: 'crank-failed', details: PolicyInputDetails ]} PolicyInputCrankFailed
- * @typedef { PolicyInputNone | PolicyInputCreateVat | PolicyInputCrankComplete | PolicyInputCrankFailed } PolicyInput
- * @typedef { boolean } PolicyOutput
- * @typedef { { vatCreated: (details: {}) => PolicyOutput,
+ * @typedef { [tag: 'cleanup', details: PolicyInputCleanupDetails] } PolicyInputCleanup
+ *
+ * @typedef { PolicyInputNone | PolicyInputCreateVat | PolicyInputCrankComplete |
+ *            PolicyInputCrankFailed | PolicyInputCleanup } PolicyInput
+ *
+ * CleanupBudget is the internal record used to limit the slow
+ * deletion of terminated vats. Each property limits the number of
+ * deletions per 'cleanup-terminated-vat' run-queue event, for a
+ * specific phase (imports, exports, snapshots, etc). It must always
+ * have a 'default' property, which is used for phases that aren't
+ * otherwise specified.
+ *
+ * @typedef { { default: number } & Partial<CleanupWork> } CleanupBudget
+ *
+ * PolicyOutputCleanupBudget is the return value of
+ * runPolicy.allowCleanup(), and tells the kernel how much it is
+ * allowed to clean up. It is either a CleanupBudget, or 'true' to
+ * allow unlimited cleanup, or 'false' to forbid any cleanup.
+ *
+ * @typedef {CleanupBudget | true | false} PolicyOutputCleanupBudget
+ *
+ * PolicyOutput is the boolean returned by all the other runPolicy
+ * methods, where 'true' means "keep going", and 'false' means "stop
+ * now".
+ *
+ * @typedef {boolean} PolicyOutput
+ *
+ * @typedef { {
+ *              allowCleanup?: () => boolean | PolicyOutputCleanupBudget,
+ *              vatCreated: (details: {}) => PolicyOutput,
  *              crankComplete: (details: { computrons?: bigint }) => PolicyOutput,
  *              crankFailed: (details: {}) => PolicyOutput,
  *              emptyCrank: () => PolicyOutput,
+ *              didCleanup?: (details: PolicyInputCleanupDetails) => PolicyOutput,
  *             } } RunPolicy
- *
+ */
+
+/**
  * @typedef {object} VatWarehousePolicy
  * @property { number } [maxVatsOnline]     Limit the number of simultaneous workers
  * @property { boolean } [restartWorkerOnSnapshot]     Reload worker immediately upon snapshot creation
@@ -292,13 +339,15 @@ export {};
  *            reconstructed via replay.  If false, no such record is kept.
  *            Defaults to true.
  * @property { number | 'never' } [reapInterval]
- *            The interval (measured in number of deliveries to the vat)
- *            after which the kernel will deliver the 'bringOutYourDead'
- *            directive to the vat.  If the value is 'never',
- *            'bringOutYourDead' will never be delivered and the vat will
- *            be responsible for internally managing (in a deterministic
- *            manner) any visible effects of garbage collection.  Defaults
- *            to the kernel's configured 'defaultReapInterval' value.
+ *            Trigger a bringOutYourDead after the vat has received
+ *            this many deliveries. If the value is 'never',
+ *            'bringOutYourDead' will not be triggered by a delivery
+ *            count (but might be triggered for other reasons).
+ * @property { number | 'never' } [reapGCKrefs]
+ *            Trigger a bringOutYourDead when the vat has been given
+ *            this many krefs in GC deliveries (dropImports,
+ *            retireImports, retireExports). If the value is 'never',
+ *            GC deliveries and their krefs are not treated specially.
  * @property { boolean } [critical]
  */
 

package/src/types-internal.js

@@ -1,6 +1,19 @@
 export {};
 
 /**
+ * The host provides (external) KernelOptions as part of the
+ * SwingSetConfig record it passes to initializeSwingset(). This
+ * internal type represents the modified form passed to
+ * initializeKernel() and kernelKeeper.createStartingKernelState .
+ *
+ * @typedef {object} InternalKernelOptions
+ * @property {ManagerType} [defaultManagerType]
+ * @property {ReapDirtThreshold} [defaultReapDirtThreshold]
+ * @property {boolean} [relaxDurabilityRules]
+ * @property {number} [snapshotInitial]
+ * @property {number} [snapshotInterval]
+ *
+ *
  * The internal data that controls which worker we use (and how we use it) is
  * stored in a WorkerOptions record, which comes in "local", "node-subprocess",
  * and "xsnap" flavors.
@@ -35,11 +48,48 @@ export {};
  * @property { boolean } enableSetup
  * @property { boolean } enablePipelining
  * @property { boolean } useTranscript
- * @property { number | 'never' } reapInterval
+ * @property { ReapDirtThreshold } reapDirtThreshold
  * @property { boolean } critical
  * @property { MeterID } [meterID] // property must be present, but can be undefined
  * @property { WorkerOptions } workerOptions
  * @property { boolean } enableDisavow
+ *
+ * @typedef ChangeVatOptions
+ * @property {number} [reapInterval]
+ */
+
+/**
+ * Reap/BringOutYourDead/BOYD Scheduling
+ *
+ * We trigger a BringOutYourDead delivery (which "reaps" all dead
+ * objects from the vat) after a certain threshold of "dirt" has
+ * accumulated. This type is used to define the thresholds for three
+ * counters: 'deliveries', 'gcKrefs', and 'computrons'. If a property
+ * is a number, we trigger BOYD when the counter for that property
+ * exceeds the threshold value. If a property is the string 'never' or
+ * missing we do not use that counter to trigger BOYD.
+ *
+ * Each vat has a .reapDirtThreshold in their vNN.options record,
+ * which overrides the kernel-wide settings in
+ * 'kernel.defaultReapDirtThreshold'
+ *
+ * @typedef {object} ReapDirtThreshold
+ * @property {number | 'never'} [deliveries]
+ * @property {number | 'never'} [gcKrefs]
+ * @property {number | 'never'} [computrons]
+ * @property {boolean} [never]
+ */
+
+/**
+ * Each counter in Dirt matches a threshold in
+ * ReapDirtThreshold. Missing values are treated as zero, so vats
+ * start with {} and accumulate dirt as deliveries are made, until a
+ * BOYD clears them.
+ *
+ * @typedef {object} Dirt
+ * @property {number} [deliveries]
+ * @property {number} [gcKrefs]
+ * @property {number} [computrons]
  */
 
 /**
@@ -86,17 +136,20 @@ export {};
  * @typedef { { type: 'upgrade-vat', vatID: VatID, upgradeID: string,
  *              bundleID: BundleID, vatParameters: SwingSetCapData,
  *              upgradeMessage: string } } RunQueueEventUpgradeVat
- * @typedef { { type: 'changeVatOptions', vatID: VatID, options: Record<string, unknown> } } RunQueueEventChangeVatOptions
+ * @typedef { { type: 'changeVatOptions', vatID: VatID, options: ChangeVatOptions } } RunQueueEventChangeVatOptions
  * @typedef { { type: 'startVat', vatID: VatID, vatParameters: SwingSetCapData } } RunQueueEventStartVat
  * @typedef { { type: 'dropExports', vatID: VatID, krefs: string[] } } RunQueueEventDropExports
  * @typedef { { type: 'retireExports', vatID: VatID, krefs: string[] } } RunQueueEventRetireExports
  * @typedef { { type: 'retireImports', vatID: VatID, krefs: string[] } } RunQueueEventRetireImports
  * @typedef { { type: 'negated-gc-action', vatID?: VatID } } RunQueueEventNegatedGCAction
  * @typedef { { type: 'bringOutYourDead', vatID: VatID } } RunQueueEventBringOutYourDead
+ * @import {CleanupBudget} from './types-external.js';
+ * @typedef { { type: 'cleanup-terminated-vat', vatID: VatID,
+ *              budget: CleanupBudget } } RunQueueEventCleanupTerminatedVat
  * @typedef { RunQueueEventNotify | RunQueueEventSend | RunQueueEventCreateVat |
  *            RunQueueEventUpgradeVat | RunQueueEventChangeVatOptions | RunQueueEventStartVat |
  *            RunQueueEventDropExports | RunQueueEventRetireExports | RunQueueEventRetireImports |
- *            RunQueueEventNegatedGCAction | RunQueueEventBringOutYourDead
+ *            RunQueueEventNegatedGCAction | RunQueueEventBringOutYourDead | RunQueueEventCleanupTerminatedVat
  *          } RunQueueEvent
  */
 

package/src/vats/comms/clist-inbound.js

@@ -1,4 +1,4 @@
-import { Fail } from '@agoric/assert';
+import { Fail } from '@endo/errors';
 import {
   flipRemoteSlot,
   insistRemoteType,

package/src/vats/comms/clist-kernel.js

@@ -1,4 +1,4 @@
-import { Fail } from '@agoric/assert';
+import { Fail } from '@endo/errors';
 import { parseVatSlot, insistVatType } from '../../lib/parseVatSlots.js';
 import { parseLocalSlot } from './parseLocalSlots.js';
 import { cdebug } from './cdebug.js';

package/src/vats/comms/clist-outbound.js

@@ -1,4 +1,4 @@
-import { Fail } from '@agoric/assert';
+import { Fail } from '@endo/errors';
 import { parseLocalSlot, insistLocalType } from './parseLocalSlots.js';
 import {
   flipRemoteSlot,

package/src/vats/comms/controller.js

@@ -1,5 +1,5 @@
 import { Nat } from '@endo/nat';
-import { assert, Fail } from '@agoric/assert';
+import { assert, Fail } from '@endo/errors';
 import { kser, kunser, kslot, krefOf } from '@agoric/kmarshal';
 
 // deliverToController() is used for local vats which want to talk to us as a

package/src/vats/comms/delivery.js

@@ -1,6 +1,6 @@
 /* eslint-disable no-use-before-define */
 
-import { assert, Fail } from '@agoric/assert';
+import { assert, Fail } from '@endo/errors';
 import { kser } from '@agoric/kmarshal';
 import { parseLocalSlot, insistLocalType } from './parseLocalSlots.js';
 import { makeUndeliverableError } from '../../lib/makeUndeliverableError.js';

package/src/vats/comms/dispatch.js

@@ -1,4 +1,4 @@
-import { assert, Fail } from '@agoric/assert';
+import { assert, Fail } from '@endo/errors';
 import { kser, kunser } from '@agoric/kmarshal';
 import { makeVatSlot } from '../../lib/parseVatSlots.js';
 import { insistMessage } from '../../lib/message.js';

package/src/vats/comms/gc-comms.js

@@ -1,4 +1,4 @@
-import { assert, Fail } from '@agoric/assert';
+import { assert, Fail } from '@endo/errors';
 import { parseVatSlot } from '../../lib/parseVatSlots.js';
 import { parseRemoteSlot } from './parseRemoteSlot.js';
 

package/src/vats/comms/parseLocalSlots.js

@@ -1,5 +1,5 @@
 import { Nat } from '@endo/nat';
-import { assert, Fail } from '@agoric/assert';
+import { assert, Fail } from '@endo/errors';
 
 // Local object/promise references (in the comms vat) contain a two-tuple of
 // (type, index).  All object references point to entries in the Local Object

package/src/vats/comms/parseRemoteSlot.js

@@ -1,5 +1,5 @@
 import { Nat } from '@endo/nat';
-import { assert, Fail } from '@agoric/assert';
+import { assert, Fail } from '@endo/errors';
 
 // Object/promise references (in remote messages) contain a three-tuple of
 // (type, allocator flag, index). The allocator flag inside an inbound

package/src/vats/comms/remote.js

@@ -1,5 +1,5 @@
 import { Nat } from '@endo/nat';
-import { assert, Fail } from '@agoric/assert';
+import { assert, Fail } from '@endo/errors';
 import { parseLocalSlot, insistLocalType } from './parseLocalSlots.js';
 import {
   makeRemoteSlot,

package/src/vats/comms/state.js

@@ -1,5 +1,5 @@
 import { Nat } from '@endo/nat';
-import { assert, Fail } from '@agoric/assert';
+import { assert, Fail } from '@endo/errors';
 import { insistCapData } from '../../lib/capdata.js';
 import {
   makeVatSlot,

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

@@ -1,9 +1,9 @@
 /* eslint-disable no-use-before-define */
 
+import { assert } from '@endo/errors';
 import { Far, E, passStyleOf } from '@endo/far';
 import { makePromiseKit } from '@endo/promise-kit';
 import { Nat } from '@endo/nat';
-import { assert } from '@agoric/assert';
 import {
   provideKindHandle,
   provideDurableMapStore,
@@ -16,8 +16,8 @@ import { makeScalarWeakMapStore } from '@agoric/store';
 import { TimeMath } from '@agoric/time';
 
 /**
- * @import {Passable, RemotableObject} from '@endo/pass-style')
- * @import {Key} from '@endo/patterns')
+ * @import {Passable, RemotableObject} from '@endo/pass-style';
+ * @import {Key} from '@endo/patterns';
  */
 
 // This consumes O(N) RAM only for outstanding promises, via wakeAt(),
@@ -25,12 +25,12 @@ import { TimeMath } from '@agoric/time';
 // client). Everything else should remain in the DB.
 
 /**
- * @import {Timestamp} from '@agoric/time'
- * @import {TimestampRecord} from '@agoric/time'
- * @import {TimestampValue} from '@agoric/time'
- * @import {RelativeTime} from '@agoric/time'
- * @import {RelativeTimeValue} from '@agoric/time'
- * @import {TimerService} from '@agoric/time'
+ * @import {Timestamp} from '@agoric/time';
+ * @import {TimestampRecord} from '@agoric/time';
+ * @import {TimestampValue} from '@agoric/time';
+ * @import {RelativeTime} from '@agoric/time';
+ * @import {RelativeTimeValue} from '@agoric/time';
+ * @import {TimerService} from '@agoric/time';
  *
  * @typedef {object} Handler
  * Handler is a user-provided Far object with .wake(time) used for callbacks

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

@@ -5,10 +5,11 @@
  * must ensure that only data goes in and out. It's also responsible for turning
  * device affordances into objects that can be used by code in other vats.
  */
+import { Nat, isNat } from '@endo/nat';
+import { q, Fail } from '@endo/errors';
 import { makePromiseKit } from '@endo/promise-kit';
 // import { makeNotifierKit } from '@agoric/notifier'; // XXX RESTORE
 import { Far, E, passStyleOf } from '@endo/far';
-import { Nat, isNat } from '@endo/nat';
 import {
   provide,
   makeScalarBigMapStore,
@@ -17,7 +18,11 @@ import {
   prepareSingleton,
 } from '@agoric/vat-data';
 
-const { quote: q, Fail } = assert;
+/**
+ * @import {VatAdminRootDeviceNode} from '../../devices/vat-admin/device-vat-admin.js';
+ * @import {DProxy} from'../plugin-manager.js';
+ * @import {Baggage} from '@agoric/vat-data';
+ */
 
 const managerTypes = ['local', 'node-subprocess', 'xsnap', 'xs-worker']; // xs-worker is alias
 
@@ -26,14 +31,25 @@ function producePRR() {
   return /** @type {const} */ ([promise, { resolve, reject }]);
 }
 
+/**
+ * Build root object of the bootstrap vat.
+ *
+ * @param {VatPowers & {
+ *   D: DProxy;
+ * }} vatPowers
+ * @param {never} _vatParameters
+ * @param {Baggage} baggage
+ */
 export function buildRootObject(vatPowers, _vatParameters, baggage) {
   const criticalVatKey = prepareSingleton(baggage, 'criticalVatKey', {});
 
   const { D } = vatPowers;
   const pendingVatCreations = new Map(); // vatID -> { resolve, reject } for promise
-  const pendingBundles = new Map(); // bundleID -> Promise<BundleCap>
+  /** @type {Map<BundleID, PromiseKit<BundleCap>>} */
+  const pendingBundles = new Map();
   const pendingUpgrades = new Map(); // upgradeID -> Promise<UpgradeResults>
 
+  /** @type {import('../plugin-manager.js').Device<VatAdminRootDeviceNode>} */
   let vatAdminDev;
 
   const runningVats = new Map(); // vatID -> [doneP, { resolve, reject }]
@@ -201,7 +217,7 @@ export function buildRootObject(vatPowers, _vatParameters, baggage) {
         console.log(`bundle ${bundleID} missing, hoping for reinstall`);
         return;
       }
-      pendingBundles.get(bundleID).resolve(bundlecap);
+      pendingBundles.get(bundleID)?.resolve(bundlecap);
       pendingBundles.delete(bundleID);
       checkForQuiescence();
     }
@@ -318,9 +334,7 @@ export function buildRootObject(vatPowers, _vatParameters, baggage) {
     noteRunningVat(vatID);
 
     const adminNode = makeAdminNode(vatID);
-    return E.when(pendingP, root => {
-      return { adminNode, root };
-    });
+    return E.when(pendingP, root => harden({ adminNode, root }));
   }
 
   function getCriticalVatKey() {
@@ -421,8 +435,9 @@ export function buildRootObject(vatPowers, _vatParameters, baggage) {
       if (!pendingBundles.has(bundleID)) {
         pendingBundles.set(bundleID, makePromiseKit());
       }
-      return pendingBundles.get(bundleID).promise;
+      return pendingBundles.get(bundleID)?.promise;
     },
+    /** @type {(bundleID: BundleID) => BundleCap} */
     getBundleCap(bundleID) {
       const bundlecap = D(vatAdminDev).getBundleCap(bundleID);
       if (bundlecap) {

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

@@ -1,4 +1,4 @@
-import { Fail } from '@agoric/assert';
+import { Fail } from '@endo/errors';
 import {
   provide,
   defineDurableKindMulti,

package/tools/bootstrap-relay.js

@@ -1,11 +1,9 @@
-import { assert } from '@agoric/assert';
+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';
 
-const { Fail, quote: q } = assert;
-
 export const buildRootObject = () => {
   const timer = buildManualTimer();
   let vatAdmin;

package/tools/bundleTool.js

@@ -1,6 +1,7 @@
 import { makeNodeBundleCache as wrappedMaker } from '@endo/bundle-source/cache.js';
 import styles from 'ansi-styles'; // less authority than 'chalk'
 
+/** @type {typeof wrappedMaker} */
 export const makeNodeBundleCache = async (dest, options, loadModule, pid) => {
   const log = (...args) => {
     const flattened = args.map(arg =>
@@ -16,8 +17,9 @@ export const makeNodeBundleCache = async (dest, options, loadModule, pid) => {
   };
   return wrappedMaker(dest, { log, ...options }, loadModule, pid);
 };
+/** @typedef {Awaited<ReturnType<typeof makeNodeBundleCache>>} BundleCache */
 
-/** @type {Map<string, ReturnType<typeof makeNodeBundleCache>>} */
+/** @type {Map<string, Promise<BundleCache>>} */
 const providedCaches = new Map();
 
 /**
@@ -28,9 +30,11 @@ const providedCaches = new Map();
  * @param {{ format?: string, dev?: boolean }} options
  * @param {(id: string) => Promise<any>} loadModule
  * @param {number} [pid]
+ * @returns {Promise<BundleCache>}
  */
 export const provideBundleCache = (dest, options, loadModule, pid) => {
   const uniqueDest = [dest, options.format, options.dev].join('-');
+  // store the promise instead of awaiting to prevent a race
   let bundleCache = providedCaches.get(uniqueDest);
   if (!bundleCache) {
     bundleCache = makeNodeBundleCache(dest, options, loadModule, pid);
@@ -40,5 +44,9 @@ export const provideBundleCache = (dest, options, loadModule, pid) => {
 };
 harden(provideBundleCache);
 
+/**
+ * @param {string} dest
+ * @returns {Promise<BundleCache>}
+ */
 export const unsafeMakeBundleCache = dest =>
   makeNodeBundleCache(dest, {}, s => import(s));

package/tools/dvo-test-harness.js

@@ -1,7 +1,7 @@
 // eslint-disable-next-line import/order
 import { test } from './prepare-test-env-ava.js';
 
-import { assert } from '@agoric/assert';
+import { assert } from '@endo/errors';
 import { makeMarshal } from '@endo/marshal';
 import { initSwingStore } from '@agoric/swing-store';
 import { initializeSwingset, makeSwingsetController } from '../src/index.js';

package/tools/manual-timer.js

@@ -1,5 +1,5 @@
+import { Fail } from '@endo/errors';
 import { Far } from '@endo/far';
-import { Fail } from '@agoric/assert';
 import { makeScalarMapStore } from '@agoric/store';
 import { bindAllMethods } from '@agoric/internal';
 import { TimeMath } from '@agoric/time';

package/tools/run-utils.js

@@ -1,4 +1,4 @@
-import { Fail, q } from '@agoric/assert';
+import { Fail, q } from '@endo/errors';
 import { kunser } from '@agoric/kmarshal';
 import { makeQueue } from '@endo/stream';