feat(vows): improve handling of ephemeral values (#9620)

refs: #9308

## Description
- adds `asPromise` helper to `VowTools` for unwrapping `Vow|Promise`, ensuring proper handling of ephemeral promises
- updates watch-utils to better handle values that are not storable durably, such as promises

### Testing Considerations
This does not include tests that simulate an upgrade - only a heap zone is used in the included tests. See #9631

### Upgrade Considerations
This PR includes changes we'd like to be in the initial release of vows.

packages/base-zone/src/watch-promise.js

@@ -9,7 +9,7 @@ const { apply } = Reflect;
 /**
  * A PromiseWatcher method guard callable with or more arguments, returning void.
  */
-export const PromiseWatcherHandler = M.call(M.any()).rest(M.any()).returns();
+export const PromiseWatcherHandler = M.call(M.raw()).rest(M.raw()).returns();
 
 /**
  * A PromiseWatcher interface that has both onFulfilled and onRejected handlers.

packages/vow/src/tools.js

@@ -5,8 +5,10 @@ import { prepareWatch } from './watch.js';
 import { prepareWatchUtils } from './watch-utils.js';
 import { makeAsVow } from './vow-utils.js';
 
-/** @import {Zone} from '@agoric/base-zone' */
-/** @import {IsRetryableReason} from './types.js' */
+/**
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {IsRetryableReason, AsPromiseFunction, EVow} from './types.js';
+ */
 
 /**
  * @param {Zone} zone
@@ -19,17 +21,26 @@ export const prepareVowTools = (zone, powers = {}) => {
   const makeVowKit = prepareVowKit(zone);
   const when = makeWhen(isRetryableReason);
   const watch = prepareWatch(zone, makeVowKit, isRetryableReason);
-  const makeWatchUtils = prepareWatchUtils(zone, watch, makeVowKit);
+  const makeWatchUtils = prepareWatchUtils(zone, {
+    watch,
+    when,
+    makeVowKit,
+    isRetryableReason,
+  });
   const watchUtils = makeWatchUtils();
   const asVow = makeAsVow(makeVowKit);
 
   /**
    * Vow-tolerant implementation of Promise.all.
    *
-   * @param {unknown[]} vows
+   * @param {EVow<unknown>[]} maybeVows
    */
-  const allVows = vows => watchUtils.all(vows);
+  const allVows = maybeVows => watchUtils.all(maybeVows);
+
+  /** @type {AsPromiseFunction} */
+  const asPromise = (specimenP, ...watcherArgs) =>
+    watchUtils.asPromise(specimenP, ...watcherArgs);
 
-  return harden({ when, watch, makeVowKit, allVows, asVow });
+  return harden({ when, watch, makeVowKit, allVows, asVow, asPromise });
 };
 harden(prepareVowTools);

packages/vow/src/types.js

@@ -29,6 +29,12 @@ export {};
  * @typedef {T | PromiseLike<T>} ERef
  */
 
+/**
+ * Eventually a value T or Vow for it.
+ * @template T
+ * @typedef {ERef<T | Vow<T>>} EVow
+ */
+
 /**
  * Follow the chain of vow shortening to the end, returning the final value.
  * This is used within E, so we must narrow the type to its remote form.
@@ -87,4 +93,18 @@ export {};
  * @property {(reason: any, ...args: C) => Vow<TResult2> | PromiseVow<TResult2> | TResult2} [onRejected]
  */
 
+/**
+ * Converts a vow or promise to a promise, ensuring proper handling of ephemeral promises.
+ *
+ * @template [T=any]
+ * @template [TResult1=T]
+ * @template [TResult2=never]
+ * @template {any[]} [C=any[]]
+ * @callback AsPromiseFunction
+ * @param {ERef<T | Vow<T>>} specimenP
+ * @param {Watcher<T, TResult1, TResult2, C>} [watcher]
+ * @param {C} [watcherArgs]
+ * @returns {Promise<TResult1 | TResult2>}
+ */
+
 /** @typedef {ReturnType<typeof prepareVowTools>} VowTools */

packages/vow/src/vow.js

@@ -4,10 +4,13 @@ import { M } from '@endo/patterns';
 import { makeTagged } from '@endo/pass-style';
 import { PromiseWatcherI } from '@agoric/base-zone';
 
+const { details: X } = assert;
+
 /**
- * @import {PromiseKit} from '@endo/promise-kit'
- * @import {Zone} from '@agoric/base-zone'
- * @import {VowResolver, VowKit} from './types.js'
+ * @import {PromiseKit} from '@endo/promise-kit';
+ * @import {Zone} from '@agoric/base-zone';
+ * @import {MapStore} from '@agoric/store';
+ * @import {VowResolver, VowKit} from './types.js';
  */
 
 const sink = () => {};
@@ -25,6 +28,9 @@ export const prepareVowKit = zone => {
   /** @type {WeakMap<VowResolver, VowEphemera>} */
   const resolverToEphemera = new WeakMap();
 
+  /** @type {WeakMap<VowResolver, any>} */
+  const resolverToNonStoredValue = new WeakMap();
+
   /**
    * Get the current incarnation's promise kit associated with a vowV0.
    *
@@ -61,30 +67,55 @@ export const prepareVowKit = zone => {
         shorten: M.call().returns(M.promise()),
       }),
       resolver: M.interface('VowResolver', {
-        resolve: M.call().optional(M.any()).returns(),
-        reject: M.call().optional(M.any()).returns(),
+        resolve: M.call().optional(M.raw()).returns(),
+        reject: M.call().optional(M.raw()).returns(),
       }),
       watchNextStep: PromiseWatcherI,
     },
     () => ({
-      value: undefined,
+      value: /** @type {any} */ (undefined),
       // The stepStatus is null if the promise step hasn't settled yet.
       stepStatus: /** @type {null | 'pending' | 'fulfilled' | 'rejected'} */ (
         null
       ),
+      isStoredValue: /** @type {boolean} */ (false),
+      /**
+       * Map for future properties that aren't in the schema.
+       * UNTIL https://github.com/Agoric/agoric-sdk/issues/7407
+       * @type {MapStore<any, any> | undefined}
+       */
+      extra: undefined,
     }),
     {
       vowV0: {
         /**
          * @returns {Promise<any>}
          */
         async shorten() {
-          const { stepStatus, value } = this.state;
+          const { stepStatus, isStoredValue, value } = this.state;
+          const { resolver } = this.facets;
+
           switch (stepStatus) {
-            case 'fulfilled':
-              return value;
-            case 'rejected':
+            case 'fulfilled': {
+              if (isStoredValue) {
+                // Always return a stored fulfilled value.
+                return value;
+              } else if (resolverToNonStoredValue.has(resolver)) {
+                // Non-stored value is available.
+                return resolverToNonStoredValue.get(resolver);
+              }
+              // We can't recover the non-stored value, so throw the
+              // explanation.
               throw value;
+            }
+            case 'rejected': {
+              if (!isStoredValue && resolverToNonStoredValue.has(resolver)) {
+                // Non-stored reason is available.
+                throw resolverToNonStoredValue.get(resolver);
+              }
+              // Always throw a stored rejection reason.
+              throw value;
+            }
             case null:
             case 'pending':
               return provideCurrentKit(this.facets.resolver).promise;
@@ -131,15 +162,38 @@ export const prepareVowKit = zone => {
         onFulfilled(value) {
           const { resolver } = this.facets;
           const { resolve } = getPromiseKitForResolution(resolver);
+          harden(value);
           if (resolve) {
             resolve(value);
           }
           this.state.stepStatus = 'fulfilled';
-          this.state.value = value;
+          this.state.isStoredValue = zone.isStorable(value);
+          if (this.state.isStoredValue) {
+            this.state.value = value;
+          } else {
+            resolverToNonStoredValue.set(resolver, value);
+            this.state.value = assert.error(
+              X`Vow fulfillment value was not stored: ${value}`,
+            );
+          }
         },
         onRejected(reason) {
+          const { resolver } = this.facets;
+          const { reject } = getPromiseKitForResolution(resolver);
+          harden(reason);
+          if (reject) {
+            reject(reason);
+          }
           this.state.stepStatus = 'rejected';
-          this.state.value = reason;
+          this.state.isStoredValue = zone.isStorable(reason);
+          if (this.state.isStoredValue) {
+            this.state.value = reason;
+          } else {
+            resolverToNonStoredValue.set(resolver, reason);
+            this.state.value = assert.error(
+              X`Vow rejection reason was not stored: ${reason}`,
+            );
+          }
         },
       },
     },