explicit heapVowTools (#9548)

refs: #9449

## Description

It was a surprise to me that the `when` from `@agoric/vow/vat.js` was heap-only. It makes sense when thinking about it, but nothing about the import triggered that thinking.

This exports `heapVowTools` to make that explicit. The consumer destructures from it what they need.

### Security Considerations
none
### Scaling Considerations
none

### Documentation Considerations
none

### Testing Considerations
CI

### Upgrade Considerations
not yet deployed, TMK

packages/boot/test/bootstrapTests/ibcClientMock.js

@@ -1,7 +1,7 @@
 /** @file Mock IBC Server */
 // @ts-check
 import { Far } from '@endo/far';
-import { V as E } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 
 /**
  * @import {Connection, PortAllocator} from '@agoric/network';

packages/boot/test/bootstrapTests/ibcServerMock.js

@@ -2,7 +2,7 @@
 // @ts-check
 import { Far } from '@endo/far';
 import { makePromiseKit } from '@endo/promise-kit';
-import { V as E } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 
 const { quote: q, Fail } = assert;
 const { log } = console;

packages/vats/src/proposals/localchain-test.js

@@ -1,5 +1,5 @@
 // @ts-check
-import { V as E } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import { typedJson } from '@agoric/cosmic-proto/vatsafe';
 
 /**

packages/vats/src/proposals/network-proposal.js

@@ -9,7 +9,9 @@ import { makeScalarBigMapStore } from '@agoric/vat-data';
 
 // Heap-based vow resolution is used for this module because the
 // bootstrap vat can't yet be upgraded.
-import { when } from '@agoric/vow/vat.js';
+import { heapVowTools } from '@agoric/vow/vat.js';
+
+const { when } = heapVowTools;
 
 /**
  * @import {ProtocolHandler} from '@agoric/network';

packages/vats/src/repl.js

@@ -2,7 +2,7 @@
 
 import { isPromise } from '@endo/promise-kit';
 import { Far } from '@endo/far';
-import { V as E } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow/vat.js';
 import * as vowExports from '@agoric/vow/vat.js';
 import * as farExports from '@endo/far';
 

packages/vats/test/localchain.test.js

@@ -8,7 +8,7 @@ import { withAmountUtils } from '@agoric/zoe/tools/test-utils.js';
 import { makeDurableZone } from '@agoric/zone/durable.js';
 import { getInterfaceOf } from '@endo/marshal';
 import { VTRANSFER_IBC_EVENT } from '@agoric/internal';
-import { prepareVowTools, V as E } from '@agoric/vow/vat.js';
+import { prepareVowTools, heapVowE as E } from '@agoric/vow/vat.js';
 import { prepareLocalChainTools } from '../src/localchain.js';
 import { prepareBridgeTargetModule } from '../src/bridge-target.js';
 import { prepareTransferTools } from '../src/transfer.js';

packages/vow/test/vat.test.js

@@ -2,7 +2,9 @@
 import test from 'ava';
 import { E, Far } from '@endo/far';
 
-import { V, makeVowKit } from '../vat.js';
+import { heapVowE, heapVowTools } from '../vat.js';
+
+const { makeVowKit } = heapVowTools;
 
 test('heap messages', async t => {
   const greeter = Far('Greeter', {
@@ -11,7 +13,7 @@ test('heap messages', async t => {
 
   /** @type {ReturnType<typeof makeVowKit<typeof greeter>>} */
   const { vow, resolver } = makeVowKit();
-  const retP = V(vow).hello('World');
+  const retP = heapVowE(vow).hello('World');
   resolver.resolve(greeter);
 
   // Happy path: WE(vow)[method](...args) calls the method.
@@ -27,10 +29,10 @@ test('heap messages', async t => {
   );
 
   // Happy path: await WE.when unwraps the vow.
-  t.is(await V.when(vow), greeter);
+  t.is(await heapVowE.when(vow), greeter);
 
   t.is(
-    await V.when(vow, res => {
+    await heapVowE.when(vow, res => {
       t.is(res, greeter);
       return 'done';
     }),

packages/vow/vat.js

@@ -1,3 +1,8 @@
+/**
+ * @file specialization of the `@agoric/vow` package for the vat disconnection rejections produced by
+ * the SwingSet kernel.
+ */
+
 /* global globalThis */
 // @ts-check
 import { isUpgradeDisconnection } from '@agoric/internal/src/upgrade-api.js';
@@ -21,21 +26,30 @@ export const defaultPowers = harden({
 });
 
 /**
+ * Produce SwingSet-compatible vowTools, with an arbitrary Zone type
+ *
  * @type {typeof rawPrepareVowTools}
  */
 export const prepareVowTools = (zone, powers = {}) =>
   rawPrepareVowTools(zone, { ...defaultPowers, ...powers });
 
-export const vowTools = prepareVowTools(makeHeapZone());
-export const { watch, when, makeVowKit, allVows } = vowTools;
+/**
+ * `vowTools` that are not durable, but are useful in non-durable clients that
+ * need to consume vows from other SwingSet vats.
+ */
+export const heapVowTools = prepareVowTools(makeHeapZone());
 
 /**
- * A vow-shortening E.  CAVEAT: This produces long-lived ephemeral
- * promises that encapsulate the shortening behaviour, and so provides no way
- * for `watch` to durably shorten.  Use the standard `import('@endo/far').E` if
- * you need to `watch` its resulting promises.
+ * A vow-shortening E, for use in vats that are not durable but receive vows.
+ *
+ * When the vows must be watched durably, use vowTools prepared in a durable zone.
+ *
+ * This produces long-lived ephemeral promises that encapsulate the shortening
+ * behaviour, and so provides no way for `watch` to durably shorten. Use the
+ * standard `import('@endo/far').E` if you need to `watch` its resulting
+ * promises.
  */
-export const V = makeE(globalThis.HandledPromise, {
-  unwrap: when,
-  additional: { when },
+export const heapVowE = makeE(globalThis.HandledPromise, {
+  unwrap: heapVowTools.when,
+  additional: { when: heapVowTools.when },
 });