@agoric/swingset-vat 0.32.3-dev-de95355.0 → 0.32.3-dev-b6c58f2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/swingset-vat",
-  "version": "0.32.3-dev-de95355.0+de95355",
+  "version": "0.32.3-dev-b6c58f2.0+b6c58f2",
   "description": "Vat/Container Launcher",
   "type": "module",
   "main": "src/index.js",
@@ -27,16 +27,16 @@
     "@types/yargs-parser": "^21.0.0"
   },
   "dependencies": {
-    "@agoric/internal": "0.3.3-dev-de95355.0+de95355",
-    "@agoric/kmarshal": "0.1.1-dev-de95355.0+de95355",
-    "@agoric/store": "0.9.3-dev-de95355.0+de95355",
-    "@agoric/swing-store": "0.9.2-dev-de95355.0+de95355",
-    "@agoric/swingset-liveslots": "0.10.3-dev-de95355.0+de95355",
-    "@agoric/swingset-xsnap-supervisor": "0.10.3-dev-de95355.0+de95355",
-    "@agoric/time": "0.3.3-dev-de95355.0+de95355",
-    "@agoric/vat-data": "0.5.3-dev-de95355.0+de95355",
-    "@agoric/xsnap": "0.14.3-dev-de95355.0+de95355",
-    "@agoric/xsnap-lockdown": "0.14.1-dev-de95355.0+de95355",
+    "@agoric/internal": "0.3.3-dev-b6c58f2.0+b6c58f2",
+    "@agoric/kmarshal": "0.1.1-dev-b6c58f2.0+b6c58f2",
+    "@agoric/store": "0.9.3-dev-b6c58f2.0+b6c58f2",
+    "@agoric/swing-store": "0.9.2-dev-b6c58f2.0+b6c58f2",
+    "@agoric/swingset-liveslots": "0.10.3-dev-b6c58f2.0+b6c58f2",
+    "@agoric/swingset-xsnap-supervisor": "0.10.3-dev-b6c58f2.0+b6c58f2",
+    "@agoric/time": "0.3.3-dev-b6c58f2.0+b6c58f2",
+    "@agoric/vat-data": "0.5.3-dev-b6c58f2.0+b6c58f2",
+    "@agoric/xsnap": "0.14.3-dev-b6c58f2.0+b6c58f2",
+    "@agoric/xsnap-lockdown": "0.14.1-dev-b6c58f2.0+b6c58f2",
     "@endo/base64": "^1.0.6",
     "@endo/bundle-source": "^3.3.0",
     "@endo/captp": "^4.2.2",
@@ -49,6 +49,7 @@
     "@endo/init": "^1.1.3",
     "@endo/marshal": "^1.5.2",
     "@endo/nat": "^5.0.9",
+    "@endo/pass-style": "^1.4.2",
     "@endo/patterns": "^1.4.2",
     "@endo/promise-kit": "^1.1.4",
     "@endo/ses-ava": "^1.2.4",
@@ -102,5 +103,5 @@
   "typeCoverage": {
     "atLeast": 75.1
   },
-  "gitHead": "de9535585f4913e792caf662d869d6f041881985"
+  "gitHead": "b6c58f297e8f902f046cc2c71fe7f6162fe0c76d"
 }

package/src/kernel/kernel.js

@@ -4,6 +4,7 @@ import { assert, Fail } from '@endo/errors';
 import { isNat } from '@endo/nat';
 import { mustMatch, M } from '@endo/patterns';
 import { importBundle } from '@endo/import-bundle';
+import { objectMetaMap } from '@agoric/internal';
 import { makeUpgradeDisconnection } from '@agoric/internal/src/upgrade-api.js';
 import { kser, kslot, makeError } from '@agoric/kmarshal';
 import { assertKnownOptions } from '../lib/assertOptions.js';
@@ -39,6 +40,7 @@ import { notifyTermination } from './notifyTermination.js';
 import { makeVatAdminHooks } from './vat-admin-hooks.js';
 
 /** @import * as liveslots from '@agoric/swingset-liveslots' */
+/** @import {PolicyInputCleanupCounts} from '../types-external.js' */
 
 function abbreviateReplacer(_, arg) {
   if (typeof arg === 'bigint') {
@@ -388,12 +390,13 @@ export default function buildKernel(
    *    illegalSyscall: { vatID: VatID, info: SwingSetCapData } | undefined,
    *    vatRequestedTermination: { reject: boolean, info: SwingSetCapData } | undefined,
    *  } } DeliveryStatus
+   * @import {PolicyInputCleanupCounts} from '../types-external.js';
    * @typedef { {
    *    abort?: boolean, // changes should be discarded, not committed
    *    consumeMessage?: boolean, // discard the aborted delivery
    *    didDelivery?: VatID, // we made a delivery to a vat, for run policy and save-snapshot
    *    computrons?: bigint, // computron count for run policy
-   *    cleanups?: number, // cleanup budget spent
+   *    cleanups?: PolicyInputCleanupCounts, // cleanup budget spent
    *    meterID?: string, // deduct those computrons from a meter
    *    measureDirt?: { vatID: VatID, dirt: Dirt }, // dirt counters should increment
    *    terminate?: { vatID: VatID, reject: boolean, info: SwingSetCapData }, // terminate vat, notify vat-admin
@@ -669,17 +672,34 @@ export default function buildKernel(
    * Perform a small (budget-limited) amount of dead-vat cleanup work.
    *
    * @param {RunQueueEventCleanupTerminatedVat} message
-   *     'message' is the run-queue cleanup action, which includes a vatID and budget.
-   *     A budget of 'undefined' allows unlimited work. Otherwise, the budget is a Number,
-   *     and cleanup should not touch more than maybe 5*budget DB rows.
+   *     'message' is the run-queue cleanup action, which includes a
+   *     vatID and budget.  The budget contains work limits for each
+   *     phase of cleanup (perhaps Infinity to allow unlimited
+   *     work). Cleanup should not touch more than maybe 5*limit DB
+   *     rows.
    * @returns {Promise<CrankResults>}
    */
   async function processCleanupTerminatedVat(message) {
     const { vatID, budget } = message;
-    const { done, cleanups } = kernelKeeper.cleanupAfterTerminatedVat(
+    const { done, work } = kernelKeeper.cleanupAfterTerminatedVat(
       vatID,
       budget,
     );
+    const zeroFreeWorkCounts = objectMetaMap(work, desc =>
+      desc.value ? desc : undefined,
+    );
+    kernelSlog.write({ type: 'vat-cleanup', vatID, work: zeroFreeWorkCounts });
+
+    /** @type {PolicyInputCleanupCounts} */
+    const cleanups = {
+      total:
+        work.exports +
+        work.imports +
+        work.kv +
+        work.snapshots +
+        work.transcripts,
+      ...work,
+    };
     if (done) {
       kernelKeeper.forgetTerminatedVat(vatID);
       kernelSlog.write({ type: 'vat-cleanup-complete', vatID });
@@ -687,8 +707,7 @@ export default function buildKernel(
     // We don't perform any deliveries here, so there are no computrons to
     // report, but we do tell the runPolicy know how much kernel-side DB
     // work we did, so it can decide how much was too much.
-    const computrons = 0n;
-    return harden({ computrons, cleanups });
+    return harden({ computrons: 0n, cleanups });
   }
 
   /**
@@ -1782,11 +1801,25 @@ export default function buildKernel(
     }
   }
 
+  // match return value of runPolicy.allowCleanup, which is
+  // PolicyOutputCleanupBudget | true | false
   const allowCleanupShape = M.or(
     // 'false' will prohibit cleanup
     false,
+    // 'true' will allow unlimited cleanup
+    true,
     // otherwise allow cleanup, optionally with a limiting budget
-    M.splitRecord({}, { budget: M.number() }, M.record()),
+    M.splitRecord(
+      { default: M.number() },
+      {
+        exports: M.number(),
+        imports: M.number(),
+        kv: M.number(),
+        snapshots: M.number(),
+        transcripts: M.number(),
+      },
+      M.record(),
+    ),
   );
 
   /**
@@ -1808,7 +1841,7 @@ export default function buildKernel(
       };
     }
     // Absent specific configuration, allow unlimited cleanup.
-    const allowCleanup = policy?.allowCleanup?.() ?? {};
+    const allowCleanup = policy?.allowCleanup?.() ?? true;
     mustMatch(harden(allowCleanup), allowCleanupShape);
 
     const message =

package/src/kernel/state/kernelKeeper.js

@@ -1,7 +1,6 @@
 /* eslint-disable no-use-before-define */
 import { Nat, isNat } from '@endo/nat';
 import { assert, Fail } from '@endo/errors';
-import { objectMetaMap } from '@agoric/internal';
 import {
   initializeVatState,
   makeVatKeeper,
@@ -46,6 +45,8 @@ const enableKernelGC = true;
  * @typedef { import('../../types-external.js').VatKeeper } VatKeeper
  * @typedef { import('../../types-internal.js').InternalKernelOptions } InternalKernelOptions
  * @typedef { import('../../types-internal.js').ReapDirtThreshold } ReapDirtThreshold
+ * @import {CleanupBudget, CleanupWork, PolicyOutputCleanupBudget} from '../../types-external.js';
+ * @import {RunQueueEventCleanupTerminatedVat} from '../../types-internal.js';
  */
 
 export { DEFAULT_REAP_DIRT_THRESHOLD_KEY };
@@ -946,11 +947,11 @@ export default function makeKernelKeeper(
    * (so the runPolicy can decide when to stop).
    *
    * @param {string} vatID
-   * @param {number} [budget]
-   * @returns {{ done: boolean, cleanups: number }}
+   * @param {CleanupBudget} budget
+   * @returns {{ done: boolean, work: CleanupWork }}
    *
    */
-  function cleanupAfterTerminatedVat(vatID, budget = undefined) {
+  function cleanupAfterTerminatedVat(vatID, budget) {
     // this is called from terminateVat, which is called from either:
     // * end of processDeliveryMessage, if crankResults.terminate
     // * device-vat-admin (when vat-v-a does adminNode.terminateVat)
@@ -960,7 +961,6 @@ export default function makeKernelKeeper(
     // crankResults.terminate
 
     insistVatID(vatID);
-    let cleanups = 0;
     const work = {
       exports: 0,
       imports: 0,
@@ -968,20 +968,7 @@ export default function makeKernelKeeper(
       snapshots: 0,
       transcripts: 0,
     };
-    let spend = _did => false; // returns "stop now"
-    if (budget !== undefined) {
-      assert.typeof(budget, 'number');
-      spend = (did = 1) => {
-        assert(budget !== undefined); // hush TSC
-        cleanups += did;
-        budget -= did;
-        return budget <= 0;
-      };
-    }
-    const logWork = () => {
-      const w = objectMetaMap(work, desc => (desc.value ? desc : undefined));
-      kernelSlog?.write({ type: 'vat-cleanup', vatID, work: w });
-    };
+    let remaining = 0;
 
     // TODO: it would be slightly cheaper to walk all kvStore keys in
     // order, and act on each one according to its category (c-list
@@ -1016,6 +1003,7 @@ export default function makeKernelKeeper(
     // used.
 
     // first, scan for exported objects, which must be orphaned
+    remaining = budget.exports ?? budget.default;
     for (const k 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
@@ -1030,13 +1018,14 @@ export default function makeKernelKeeper(
       // note: adds to maybeFreeKrefs, deletes c-list and .owner
       orphanKernelObject(kref, vatID);
       work.exports += 1;
-      if (spend()) {
-        logWork();
-        return { done: false, cleanups };
+      remaining -= 1;
+      if (remaining <= 0) {
+        return { done: false, work };
       }
     }
 
     // then scan for imported objects, which must be decrefed
+    remaining = budget.imports ?? budget.default;
     for (const k of enumeratePrefixedKeys(kvStore, importPrefix)) {
       // abandoned imports: delete the clist entry as if the vat did a
       // drop+retire
@@ -1045,9 +1034,9 @@ export default function makeKernelKeeper(
       vatKeeper.deleteCListEntry(kref, vref);
       // that will also delete both db keys
       work.imports += 1;
-      if (spend()) {
-        logWork();
-        return { done: false, cleanups };
+      remaining -= 1;
+      if (remaining <= 0) {
+        return { done: false, work };
       }
     }
 
@@ -1055,30 +1044,32 @@ export default function makeKernelKeeper(
     // so they already know the orphaned promises to reject
 
     // now loop back through everything and delete it all
+    remaining = budget.kv ?? budget.default;
     for (const k of enumeratePrefixedKeys(kvStore, `${vatID}.`)) {
       kvStore.delete(k);
       work.kv += 1;
-      if (spend()) {
-        logWork();
-        return { done: false, cleanups };
+      remaining -= 1;
+      if (remaining <= 0) {
+        return { done: false, work };
       }
     }
 
     // this will internally loop through 'budget' deletions
-    const dsc = vatKeeper.deleteSnapshots(budget);
+    remaining = budget.snapshots ?? budget.default;
+    const dsc = vatKeeper.deleteSnapshots(remaining);
     work.snapshots += dsc.cleanups;
-    if (spend(dsc.cleanups)) {
-      logWork();
-      return { done: false, cleanups };
+    remaining -= dsc.cleanups;
+    if (remaining <= 0) {
+      return { done: false, work };
     }
 
     // same
-    const dts = vatKeeper.deleteTranscripts(budget);
+    remaining = budget.transcripts ?? budget.default;
+    const dts = vatKeeper.deleteTranscripts(remaining);
     work.transcripts += dts.cleanups;
+    remaining -= dts.cleanups;
     // last task, so increment cleanups, but dc.done is authoritative
-    spend(dts.cleanups);
-    logWork();
-    return { done: dts.done, cleanups };
+    return { done: dts.done, work };
   }
 
   function deleteVatID(vatID) {
@@ -1385,20 +1376,23 @@ export default function makeKernelKeeper(
     kvStore.set(`vats.terminated`, JSON.stringify(terminatedVats));
   }
 
+  /**
+   * @param {PolicyOutputCleanupBudget} allowCleanup
+   * @returns {RunQueueEventCleanupTerminatedVat | undefined}
+   */
   function nextCleanupTerminatedVatAction(allowCleanup) {
-    if (!allowCleanup) {
+    if (allowCleanup === false) {
+      return undefined;
+    } else {
+      const unlimited = { default: Infinity };
+      /** @type {CleanupBudget} */
+      const budget = allowCleanup === true ? unlimited : allowCleanup;
+      const vatID = getFirstTerminatedVat();
+      if (vatID) {
+        return { type: 'cleanup-terminated-vat', vatID, budget };
+      }
       return undefined;
     }
-    // budget === undefined means "unlimited"
-    const { budget } = allowCleanup;
-    // if (getGCActions().size) {
-    //  return undefined;
-    // }
-    const vatID = getFirstTerminatedVat();
-    if (vatID) {
-      return { type: 'cleanup-terminated-vat', vatID, budget };
-    }
-    return undefined;
   }
 
   // As refcounts are decremented, we accumulate a set of krefs for which

package/src/lib/runPolicies.js

@@ -4,7 +4,7 @@ export function foreverPolicy() {
   /** @type { RunPolicy } */
   return harden({
     allowCleanup() {
-      return {}; // unlimited budget
+      return true; // unlimited budget
     },
     vatCreated(_details) {
       return true;
@@ -31,7 +31,7 @@ export function crankCounter(
   /** @type { RunPolicy } */
   const policy = harden({
     allowCleanup() {
-      return { budget: 100 }; // limited budget
+      return { default: 100 }; // limited budget
     },
     vatCreated() {
       vats += 1;
@@ -64,7 +64,7 @@ export function computronCounter(limit, options = {}) {
   /** @type { RunPolicy } */
   const policy = harden({
     allowCleanup() {
-      return { budget: cleanupBudget }; // limited budget
+      return { default: cleanupBudget }; // limited budget
     },
     vatCreated() {
       total += vatCreatedComputrons;
@@ -93,7 +93,7 @@ export function wallClockWaiter(seconds) {
   const timeout = Date.now() + 1000 * seconds;
   /** @type { RunPolicy } */
   const policy = harden({
-    allowCleanup: () => ({}), // unlimited budget
+    allowCleanup: () => true, // unlimited budget
     vatCreated: () => Date.now() < timeout,
     crankComplete: () => Date.now() < timeout,
     crankFailed: () => Date.now() < timeout,
@@ -121,7 +121,7 @@ export function someCleanup(budget) {
     allowCleanup: () => {
       if (once) {
         once = false;
-        return { budget };
+        return { default: budget };
       }
       return false;
     },

package/src/types-external.js

@@ -219,24 +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 { [tag: 'cleanup', details: { cleanups: number, computrons?: number }] } PolicyInputCleanup
+ * @typedef { [tag: 'cleanup', details: PolicyInputCleanupDetails] } PolicyInputCleanup
+ *
  * @typedef { PolicyInputNone | PolicyInputCreateVat | PolicyInputCrankComplete |
  *            PolicyInputCrankFailed | PolicyInputCleanup } PolicyInput
- * @typedef { boolean } PolicyOutput
+ *
+ * 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?: () => false | { budget?: number },
+ *              allowCleanup?: () => boolean | PolicyOutputCleanupBudget,
  *              vatCreated: (details: {}) => PolicyOutput,
  *              crankComplete: (details: { computrons?: bigint }) => PolicyOutput,
  *              crankFailed: (details: {}) => PolicyOutput,
  *              emptyCrank: () => PolicyOutput,
- *              didCleanup?: (details: { cleanups: number }) => 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

package/src/types-internal.js

@@ -143,8 +143,9 @@ export {};
  * @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: number | undefined } } RunQueueEventCleanupTerminatedVat
+ *              budget: CleanupBudget } } RunQueueEventCleanupTerminatedVat
  * @typedef { RunQueueEventNotify | RunQueueEventSend | RunQueueEventCreateVat |
  *            RunQueueEventUpgradeVat | RunQueueEventChangeVatOptions | RunQueueEventStartVat |
  *            RunQueueEventDropExports | RunQueueEventRetireExports | RunQueueEventRetireImports |