@agoric/vow 0.2.0-upgrade-16-dev-12b78e3.0 → 0.2.0-upgrade-17-dev-a61cdab.0

package/README.md

@@ -26,12 +26,12 @@ Here they are: {
 }
 ```
 
-On Agoric, you can use `V` exported from `@agoric/vow/vat.js`, which
-converts a chain of promises and vows to a promise for its final
-fulfilment, by unwrapping any intermediate vows:
+You can use `heapVowE` exported from `@agoric/vow`, which converts a chain of
+promises and vows to a promise for its final fulfilment, by unwrapping any
+intermediate vows:
 
 ```js
-import { V as E } from '@agoric/vow/vat.js';
+import { heapVowE as E } from '@agoric/vow';
 [...]
 const a = await E.when(w1);
 const b = await E(w2).something(...args);
@@ -40,12 +40,13 @@ const b = await E(w2).something(...args);
 
 ## Vow Producer
 
-On Agoric, use the following to create and resolve a vow:
+Use the following to create and resolve a vow:
 
 ```js
-// CAVEAT: `V` uses internal ephemeral promises, so while it is convenient,
+// CAVEAT: `heapVow*` uses internal ephemeral promises, so while it is convenient,
 // it cannot be used by upgradable vats.  See "Durability" below:
-import { V as E, makeVowKit } from '@agoric/vow/vat.js';
+import { heapVowE, heapVowTools } from '@agoric/vow';
+const { makeVowKit } = heapVowTools;
 [...]
 const { resolver, vow } = makeVowKit();
 // Send vow to a potentially different vat.
@@ -56,15 +57,15 @@ resolver.resolve('now you know the answer');
 
 ## Durability
 
-The `@agoric/vow/vat.js` module allows vows to integrate Agoric's vat upgrade
-mechanism.  To create vow tools that deal with durable objects:
+By default, the `@agoric/vow` module allows vows to integrate with Agoric's vat
+upgrade mechanism.  To create vow tools that deal with durable objects:
 
 ```js
 // NOTE: Cannot use `V` as it has non-durable internal state when unwrapping
 // vows.  Instead, use the default vow-exposing `E` with the `watch`
 // operator.
 import { E } from '@endo/far';
-import { prepareVowTools } from '@agoric/vow/vat.js';
+import { prepareVowTools } from '@agoric/vow';
 import { makeDurableZone } from '@agoric/zone';
 
 // Only do the following once at the start of a new vat incarnation:
@@ -94,20 +95,25 @@ final result:
 // that may not be side-effect free.
 let result = await specimenP;
 let vowInternals = getVowInternals(result);
+let disconnectionState = undefined;
 // Loop until the result is no longer a vow.
 while (vowInternals) {
   try {
-    const shortened = await E(internals.vowV0).shorten();
+    // WARNING: Do not use `shorten()` in your own code.  This is an example
+    // for didactic purposes only.
+    const shortened = await E(vowInternals.vowV0).shorten();
     const nextInternals = getVowInternals(shortened);
     // Atomically update the state.
     result = shortened;
     vowInternals = nextInternals;
   } catch (e) {
-    if (!isDisconnectionReason(e)) {
+    const nextDisconnectionState = isDisconnectionReason(e, disconnectionState);
+    if (!nextDisconnectionState) {
       // Not a disconnect, so abort.
       throw e;
     }
-    // It was a disconnect, so try again with the same state.
+    // It was a disconnect, so try again with the updated state.
+    disconnectionState = nextDisconnectionState;
   }
 }
 return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agoric/vow",
-  "version": "0.2.0-upgrade-16-dev-12b78e3.0+12b78e3",
+  "version": "0.2.0-upgrade-17-dev-a61cdab.0+a61cdab",
   "description": "Remote (shortening and disconnection-tolerant) Promise-likes",
   "type": "module",
   "main": "src/index.js",
@@ -20,19 +20,21 @@
     "lint:types": "tsc"
   },
   "dependencies": {
-    "@agoric/base-zone": "0.1.1-upgrade-16-dev-12b78e3.0+12b78e3",
-    "@agoric/internal": "0.4.0-upgrade-16-dev-12b78e3.0+12b78e3",
-    "@endo/env-options": "^1.1.4",
-    "@endo/eventual-send": "^1.2.2",
-    "@endo/pass-style": "^1.4.0",
-    "@endo/patterns": "^1.4.0",
-    "@endo/promise-kit": "^1.1.2"
+    "@agoric/base-zone": "0.1.1-upgrade-17-dev-a61cdab.0+a61cdab",
+    "@agoric/internal": "0.4.0-upgrade-17-dev-a61cdab.0+a61cdab",
+    "@endo/env-options": "^1.1.6",
+    "@endo/errors": "^1.2.5",
+    "@endo/eventual-send": "^1.2.5",
+    "@endo/pass-style": "^1.4.3",
+    "@endo/patterns": "^1.4.3",
+    "@endo/promise-kit": "^1.1.5"
   },
   "devDependencies": {
     "@agoric/internal": "^0.3.2",
-    "@endo/far": "^1.1.2",
-    "@endo/init": "^1.1.2",
-    "ava": "^5.3.0"
+    "@endo/far": "^1.1.5",
+    "@endo/init": "^1.1.4",
+    "ava": "^5.3.0",
+    "tsd": "^0.31.1"
   },
   "ava": {
     "require": [
@@ -52,7 +54,7 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 89.6
+    "atLeast": 89.96
   },
-  "gitHead": "12b78e307e22d0dc0c95f40099300e16655781c4"
+  "gitHead": "a61cdabb23bd2c846e003dee7326018a7462a929"
 }

package/src/E.js

@@ -15,10 +15,10 @@
  * designed to be a drop-in replacement for the version in
  * `@endo/eventual-send/src/E.js` which contained no concept of "unwrap",
  */
+import { X, q, Fail, makeError } from '@endo/errors';
 import { trackTurns } from './track-turns.js';
 import { makeMessageBreakpointTester } from './message-breakpoints.js';
 
-const { details: X, quote: q, Fail } = assert;
 const { assign, create } = Object;
 
 const onSend = makeMessageBreakpointTester('ENDO_SEND_BREAKPOINTS');
@@ -79,7 +79,7 @@ const makeEProxyHandler = (recipient, HandledPromise, unwrap) =>
             if (this !== receiver) {
               // Reject the async function call
               return HandledPromise.reject(
-                assert.error(
+                makeError(
                   X`Unexpected receiver for "${q(propertyKey)}" method of E(${q(
                     recipient,
                   )})`,

package/src/index.d.ts

@@ -1,6 +1,7 @@
-export * from "./tools.js";
+export * from "../vat.js";
 export * from "./types.js";
 export * from "@agoric/internal/src/types.js";
 export { default as makeE } from "./E.js";
+export type VowTools = import("./tools.js").VowTools;
 export { VowShape, toPassableCap } from "./vow-utils.js";
 //# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["index.js"],"names":[],"mappings":";;;;uBASa,OAAO,YAAY,EAAE,QAAQ"}

package/src/index.js

@@ -1,8 +1,15 @@
 // @ts-check
-export * from './tools.js';
+
+// We default to the vat-compatible version of this package, which is easy to
+// reconfigure if not running under SwingSet.
+export * from '../vat.js';
 export { default as makeE } from './E.js';
 export { VowShape, toPassableCap } from './vow-utils.js';
 
+/**
+ * @typedef {import('./tools.js').VowTools} VowTools
+ */
+
 // eslint-disable-next-line import/export
 export * from './types.js';
 

package/src/message-breakpoints.js

@@ -1,7 +1,7 @@
 // @ts-check
 import { getEnvironmentOption } from '@endo/env-options';
 
-const { quote: q, Fail } = assert;
+import { q, Fail } from '@endo/errors';
 
 const { hasOwn, freeze, entries } = Object;
 

package/src/tools.d.ts

@@ -1,15 +1,18 @@
-export function prepareVowTools(zone: Zone, powers?: {
+export function prepareBasicVowTools(zone: Zone, powers?: {
     isRetryableReason?: IsRetryableReason | undefined;
 } | undefined): {
     when: <T, TResult1 = import("./types.js").EUnwrap<T>, TResult2 = never>(specimenP: T, onFulfilled?: ((value: import("./types.js").EUnwrap<T>) => TResult1 | PromiseLike<TResult1>) | undefined, onRejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined) => Promise<TResult1 | TResult2>;
-    watch: <T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]>(specimenP: EVow<T>, watcher?: import("./types.js").Watcher<T, TResult1, TResult2, C> | undefined, ...watcherArgs: C) => import("./types.js").Vow<Exclude<TResult1, void> | Exclude<TResult2, void> extends never ? TResult1 : Exclude<TResult1, void> | Exclude<TResult2, void>>;
+    watch: <T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]>(specimenP: EVow<T>, watcher?: import("./types.js").Watcher<T, TResult1, TResult2, C> | undefined, ...watcherArgs: C) => Vow<Exclude<TResult1, void> | Exclude<TResult2, void> extends never ? TResult1 : Exclude<TResult1, void> | Exclude<TResult2, void>>;
     makeVowKit: <T>() => import("./types.js").VowKit<T>;
-    allVows: (maybeVows: EVow<unknown>[]) => import("./types.js").Vow<any[]>;
-    asVow: <T extends unknown>(fn: (...args: any[]) => import("./types.js").Vow<Awaited<T>> | Awaited<T>) => import("./types.js").Vow<Awaited<T>>;
+    allVows: (maybeVows: EVow<unknown>[]) => Vow<any[]>;
+    asVow: <T extends unknown>(fn: (...args: any[]) => Vow<Awaited<T>> | Awaited<T> | import("./types.js").PromiseVow<T>) => Vow<Awaited<T>>;
     asPromise: AsPromiseFunction;
+    retriable: <F extends (...args: any[]) => Promise<any>>(fnZone: Zone, name: string, fn: F) => F extends (...args: infer Args) => Promise<infer R> ? (...args: Args) => Vow<R> : never;
 };
+export type VowTools = ReturnType<typeof prepareBasicVowTools>;
 import type { Zone } from '@agoric/base-zone';
 import type { IsRetryableReason } from './types.js';
 import type { EVow } from './types.js';
+import type { Vow } from './types.js';
 import type { AsPromiseFunction } from './types.js';
 //# sourceMappingURL=tools.d.ts.map

package/src/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["tools.js"],"names":[],"mappings":"AAiBO,sCAJI,IAAI;;;;;;yBAsBF,KAAK,OAAO,CAAC,EAAE;oCAW4nC,GAAG;;EAF1pC;0BApCsB,mBAAmB;uCACmB,YAAY;0BAAZ,YAAY;uCAAZ,YAAY"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["tools.js"],"names":[],"mappings":"AAoBO,2CAJI,IAAI;;;;;;yBAwCF,KAAK,OAAO,CAAC,EAAE;oCAqB8U,GAAG;;gBArC3T,CAAC,SAApC,CAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC,GAAG,CAAE,UACpC,IAAI,QACJ,MAAM,MACN,CAAC,KACC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC,GAAG,KAAK;EA6BrG;uBAGa,UAAU,CAAC,OAAO,oBAAoB,CAAC;0BApE9B,mBAAmB;uCAC8B,YAAY;0BAAZ,YAAY;yBAAZ,YAAY;uCAAZ,YAAY"}

package/src/tools.js

@@ -1,21 +1,24 @@
 // @ts-check
-import { makeWhen } from './when.js';
+import { makeAsVow } from './vow-utils.js';
 import { prepareVowKit } from './vow.js';
-import { prepareWatch } from './watch.js';
 import { prepareWatchUtils } from './watch-utils.js';
-import { makeAsVow } from './vow-utils.js';
+import { prepareWatch } from './watch.js';
+import { makeWhen } from './when.js';
 
 /**
  * @import {Zone} from '@agoric/base-zone';
- * @import {IsRetryableReason, AsPromiseFunction, EVow} from './types.js';
+ * @import {IsRetryableReason, AsPromiseFunction, EVow, Vow, ERef} from './types.js';
  */
 
 /**
+ * NB: Not to be used in a Vat. It doesn't know what an upgrade is. For that you
+ * need `prepareVowTools` from `vat.js`.
+ *
  * @param {Zone} zone
  * @param {object} [powers]
  * @param {IsRetryableReason} [powers.isRetryableReason]
  */
-export const prepareVowTools = (zone, powers = {}) => {
+export const prepareBasicVowTools = (zone, powers = {}) => {
   const { isRetryableReason = /** @type {IsRetryableReason} */ (() => false) } =
     powers;
   const makeVowKit = prepareVowKit(zone);
@@ -30,6 +33,24 @@ export const prepareVowTools = (zone, powers = {}) => {
   const watchUtils = makeWatchUtils();
   const asVow = makeAsVow(makeVowKit);
 
+  /**
+   * TODO FIXME make this real
+   * Create a function that retries the given function if the underlying
+   * functions rejects due to upgrade disconnection.
+   *
+   * @template {(...args: any[]) => Promise<any>} F
+   * @param {Zone} fnZone - the zone for the named function
+   * @param {string} name
+   * @param {F} fn
+   * @returns {F extends (...args: infer Args) => Promise<infer R> ? (...args: Args) => Vow<R> : never}
+   */
+  const retriable =
+    (fnZone, name, fn) =>
+    // @ts-expect-error cast
+    (...args) => {
+      return watch(fn(...args));
+    };
+
   /**
    * Vow-tolerant implementation of Promise.all.
    *
@@ -41,6 +62,16 @@ export const prepareVowTools = (zone, powers = {}) => {
   const asPromise = (specimenP, ...watcherArgs) =>
     watchUtils.asPromise(specimenP, ...watcherArgs);
 
-  return harden({ when, watch, makeVowKit, allVows, asVow, asPromise });
+  return harden({
+    when,
+    watch,
+    makeVowKit,
+    allVows,
+    asVow,
+    asPromise,
+    retriable,
+  });
 };
-harden(prepareVowTools);
+harden(prepareBasicVowTools);
+
+/** @typedef {ReturnType<typeof prepareBasicVowTools>} VowTools */

package/src/track-turns.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"track-turns.d.ts","sourceRoot":"","sources":["track-turns.js"],"names":[],"mappings":"AAyFO,2BAJwB,CAAC,SAAlB,aAAa,EAAG,SACnB,CAAC,GACC,CAAC,CAmBb;;;;;4BAMY,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,GAAG,SAAS"}
+{"version":3,"file":"track-turns.d.ts","sourceRoot":"","sources":["track-turns.js"],"names":[],"mappings":"AA2FO,2BAJwB,CAAC,SAAlB,aAAa,EAAG,SACnB,CAAC,GACC,CAAC,CAkBb;;;;;4BAMY,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,GAAG,SAAS"}

package/src/track-turns.js

@@ -5,8 +5,10 @@ import {
   environmentOptionsListHas,
 } from '@endo/env-options';
 
-// NOTE: We can't import these because they're not in scope before lockdown.
-// import { assert, details as X, Fail } from '@agoric/assert';
+// Note that in the original track-turns.js in @endo/eventual-send we
+// can't simply import these because `assert` is not in scope before lockdown.
+// But this copy in @agoric/vow the import is fine.
+import { annotateError, X } from '@endo/errors';
 
 // WARNING: Global Mutable State!
 // This state is communicated to `assert` that makes it available to the
@@ -34,7 +36,7 @@ const ENABLED =
 
 const addRejectionNote = detailsNote => reason => {
   if (reason instanceof Error) {
-    assert.note(reason, detailsNote);
+    annotateError(reason, detailsNote);
   }
   if (VERBOSE) {
     console.log('REJECTED at top of event loop', reason);
@@ -42,7 +44,7 @@ const addRejectionNote = detailsNote => reason => {
 };
 
 const wrapFunction =
-  (func, sendingError, X) =>
+  (func, sendingError) =>
   (...args) => {
     hiddenPriorError = sendingError;
     hiddenCurrentTurn += 1;
@@ -53,7 +55,7 @@ const wrapFunction =
         result = func(...args);
       } catch (err) {
         if (err instanceof Error) {
-          assert.note(
+          annotateError(
             err,
             X`Thrown from: ${hiddenPriorError}:${hiddenCurrentTurn}.${hiddenCurrentEvent}`,
           );
@@ -91,18 +93,17 @@ export const trackTurns = funcs => {
   if (!ENABLED || typeof globalThis === 'undefined' || !globalThis.assert) {
     return funcs;
   }
-  const { details: X } = assert;
 
   hiddenCurrentEvent += 1;
   const sendingError = Error(
     `Event: ${hiddenCurrentTurn}.${hiddenCurrentEvent}`,
   );
   if (hiddenPriorError !== undefined) {
-    assert.note(sendingError, X`Caused by: ${hiddenPriorError}`);
+    annotateError(sendingError, X`Caused by: ${hiddenPriorError}`);
   }
 
   return /** @type {T} */ (
-    funcs.map(func => func && wrapFunction(func, sendingError, X))
+    funcs.map(func => func && wrapFunction(func, sendingError))
   );
 };
 

package/src/types.d.ts

@@ -52,9 +52,7 @@ export type Watcher<T = any, TResult1 = T, TResult2 = never, C extends any[] = a
  * Converts a vow or promise to a promise, ensuring proper handling of ephemeral promises.
  */
 export type AsPromiseFunction<T = any, TResult1 = T, TResult2 = never, C extends any[] = any[]> = (specimenP: ERef<T | Vow<T>>, watcher?: Watcher<T, TResult1, TResult2, C> | undefined, watcherArgs?: C | undefined) => Promise<TResult1 | TResult2>;
-export type VowTools = ReturnType<typeof prepareVowTools>;
 import type { RemotableObject } from '@endo/pass-style';
 import type { Remote } from '@agoric/internal';
 import type { CopyTagged } from '@endo/pass-style';
-import type { prepareVowTools } from './tools.js';
 //# sourceMappingURL=types.d.ts.map

package/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":";;;yCAaW,GAAG,mBACH,GAAG,KAED,GAAG;;;;;uBAKH,CAAC,IACD,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;iBAKnB,CAAC,IACD,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;;;;iBAKlB,CAAC,IACD,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;;;;;oBAMhB,CAAC,IACD,CACZ,CAAK,SAAS,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvC,CAAK,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC/C,CAAK,CACF;;;;;;;kBAIU,CAAC;;;;;;;aAMD,MAAM,OAAO,CAAC,CAAC,CAAC;;uBAOhB,CAAC;WAED,eAAe,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;;gBAIlC,CAAC,UACF,WAAW,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;mBAI/B,CAAC,UACF;IACZ,GAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAChB,QAAY,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CAC1B;wBAIU,CAAC,UACF;IAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;CAAE;oBAIvE,CAAC,QACD,QAAQ,MACR,QAAQ,UACA,CAAC,SAAT,GAAG,EAAG;2BAEE,CAAC,WAAW,CAAC,KAAK,GAAG,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,QAAQ;2BAChE,GAAG,WAAW,CAAC,KAAK,GAAG,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,QAAQ;;;;;8BAM5E,CAAC,QACD,QAAQ,MACR,QAAQ,UACA,CAAC,SAAT,GAAG,EAAG,wBAET,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,2FAGd,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;uBAG3B,UAAU,CAAC,sBAAsB,CAAC;qCAxGd,kBAAkB;4BAC3B,kBAAkB;gCAFd,kBAAkB;qCAGb,YAAY"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.js"],"names":[],"mappings":";;;yCAaW,GAAG,mBACH,GAAG,KAED,GAAG;;;;;uBAKH,CAAC,IACD,OAAO,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;iBAKnB,CAAC,IACD,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;;;;iBAKlB,CAAC,IACD,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;;;;;oBAMhB,CAAC,IACD,CACZ,CAAK,SAAS,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACvC,CAAK,SAAS,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAC/C,CAAK,CACF;;;;;;;kBAIU,CAAC;;;;;;;aAMD,MAAM,OAAO,CAAC,CAAC,CAAC;;uBAOhB,CAAC;WAED,eAAe,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;;gBAIlC,CAAC,UACF,WAAW,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;mBAI/B,CAAC,UACF;IACZ,GAAO,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC;IAChB,QAAY,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;CAC1B;wBAIU,CAAC,UACF;IAAE,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;CAAE;oBAIvE,CAAC,QACD,QAAQ,MACR,QAAQ,UACA,CAAC,SAAT,GAAG,EAAG;2BAEE,CAAC,WAAW,CAAC,KAAK,GAAG,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,QAAQ;2BAChE,GAAG,WAAW,CAAC,KAAK,GAAG,CAAC,QAAQ,CAAC,GAAG,UAAU,CAAC,QAAQ,CAAC,GAAG,QAAQ;;;;;8BAM5E,CAAC,QACD,QAAQ,MACR,QAAQ,UACA,CAAC,SAAT,GAAG,EAAG,wBAET,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,2FAGd,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;qCArGP,kBAAkB;4BAC3B,kBAAkB;gCAFd,kBAAkB"}

package/src/types.js

@@ -106,5 +106,3 @@ export {};
  * @param {C} [watcherArgs]
  * @returns {Promise<TResult1 | TResult2>}
  */
-
-/** @typedef {ReturnType<typeof prepareVowTools>} VowTools */

package/src/vow-utils.d.ts

@@ -3,10 +3,11 @@ export const VowShape: import("@endo/patterns").Matcher;
 export function isVow(specimen: unknown): specimen is Vow;
 export function getVowPayload<T>(specimen: any): VowPayload<T> | undefined;
 export function toPassableCap(k: PassableCap | Vow): PassableCap;
-export function makeAsVow(makeVowKit: MakeVowKit): <T extends unknown>(fn: (...args: any[]) => Vow<Awaited<T>> | Awaited<T>) => Vow<Awaited<T>>;
+export function makeAsVow(makeVowKit: MakeVowKit): <T extends unknown>(fn: (...args: any[]) => Vow<Awaited<T>> | Awaited<T> | PromiseVow<T>) => Vow<Awaited<T>>;
 import { E as basicE } from '@endo/eventual-send';
 import type { Vow } from './types.js';
 import type { VowPayload } from './types.js';
 import type { PassableCap } from '@endo/pass-style';
 import type { MakeVowKit } from './vow.js';
+import type { PromiseVow } from './types.js';
 //# sourceMappingURL=vow-utils.d.ts.map

package/src/vow-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vow-utils.d.ts","sourceRoot":"","sources":["vow-utils.js"],"names":[],"mappings":";AAaA,wDAKE;AAMK,gCAHI,OAAO,GACL,QAAQ,IAAI,GAAG,CAGyB;AAc9C,8BAJM,CAAC,YACH,GAAG,GACD,WAAW,CAAC,CAAC,GAAG,SAAS,CASrC;AAoBM,iCAHI,WAAW,GAAG,GAAG,GACf,WAAW,CAUvB;AAIM,sCADK,UAAU,IAKD,CAAC,sBACT,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,KAC9C,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,CAiB7B;4BApG2B,qBAAqB;yBAMf,YAAY;gCAAZ,YAAY;iCADhB,kBAAkB;gCAEnB,UAAU"}
+{"version":3,"file":"vow-utils.d.ts","sourceRoot":"","sources":["vow-utils.js"],"names":[],"mappings":";AAaA,wDAKE;AAMK,gCAHI,OAAO,GACL,QAAQ,IAAI,GAAG,CAGyB;AAc9C,8BAJM,CAAC,YACH,GAAG,GACD,WAAW,CAAC,CAAC,GAAG,SAAS,CASrC;AAoBM,iCAHI,WAAW,GAAG,GAAG,GACf,WAAW,CAUvB;AAIM,sCADK,UAAU,IAKD,CAAC,sBACT,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,KAC9D,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,CAiB7B;4BApG2B,qBAAqB;yBAMH,YAAY;gCAAZ,YAAY;iCAD5B,kBAAkB;gCAEnB,UAAU;gCADO,YAAY"}

package/src/vow-utils.js

@@ -5,7 +5,7 @@ import { M, matches } from '@endo/patterns';
 
 /**
  * @import {PassableCap} from '@endo/pass-style';
- * @import {VowPayload, Vow} from './types.js';
+ * @import {VowPayload, Vow, PromiseVow} from './types.js';
  * @import {MakeVowKit} from './vow.js';
  */
 
@@ -81,7 +81,7 @@ export const makeAsVow = makeVowKit => {
    * Helper function that coerces the result of a function to a Vow. Helpful
    * for scenarios like a synchronously thrown error.
    * @template {any} T
-   * @param {(...args: any[]) => Vow<Awaited<T>> | Awaited<T>} fn
+   * @param {(...args: any[]) => Vow<Awaited<T>> | Awaited<T> | PromiseVow<T>} fn
    * @returns {Vow<Awaited<T>>}
    */
   const asVow = fn => {
@@ -94,9 +94,9 @@ export const makeAsVow = makeVowKit => {
     if (isVow(result)) {
       return result;
     }
-    const kit = makeVowKit();
-    kit.resolver.resolve(result);
-    return kit.vow;
+    const { vow, resolver } = makeVowKit();
+    resolver.resolve(result);
+    return vow;
   };
   return harden(asVow);
 };

package/src/vow.js

@@ -120,7 +120,7 @@ export const prepareVowKit = zone => {
             case 'pending':
               return provideCurrentKit(this.facets.resolver).promise;
             default:
-              throw new TypeError(`unexpected stepStatus ${stepStatus}`);
+              throw TypeError(`unexpected stepStatus ${stepStatus}`);
           }
         },
       },

package/src/when.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"when.d.ts","sourceRoot":"","sources":["when.js"],"names":[],"mappings":"AAQO,8EAMQ,CAAC,EACA,QAAQ,eACR,QAAQ,qBACX,CAAC,yBACO,QAAQ,CAAC,CAAC,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,sCAC9C,GAAG,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,kBAC/C,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAmD1C;mBAIa,UAAU,CAAC,OAAO,QAAQ,CAAC;uCAxEO,YAAY;6BAAZ,YAAY"}
+{"version":3,"file":"when.d.ts","sourceRoot":"","sources":["when.js"],"names":[],"mappings":"AAQO,8EAiEQ,CAAC,EACA,QAAQ,eACR,QAAQ,qBACX,CAAC,yBACO,QAAQ,CAAC,CAAC,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,sCAC9C,GAAG,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,kBAC/C,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC,CAc1C;mBAIa,UAAU,CAAC,OAAO,QAAQ,CAAC;uCA9FO,YAAY;6BAAZ,YAAY"}

package/src/when.js

@@ -12,15 +12,15 @@ export const makeWhen = (
   /**
    * Shorten `specimenP` until we achieve a final result.
    *
+   * Does not survive upgrade (even if specimenP is a durable Vow).
+   *
+   * @see {@link ../../README.md}
+   *
    * @template T
-   * @template [TResult1=EUnwrap<T>]
-   * @template [TResult2=never]
    * @param {T} specimenP value to unwrap
-   * @param {(value: EUnwrap<T>) => TResult1 | PromiseLike<TResult1>} [onFulfilled]
-   * @param {(reason: any) => TResult2 | PromiseLike<TResult2>} [onRejected]
-   * @returns {Promise<TResult1 | TResult2>}
+   * @returns {Promise<EUnwrap<T>>}
    */
-  const when = async (specimenP, onFulfilled, onRejected) => {
+  const unwrap = async specimenP => {
     // Ensure we don't run until a subsequent turn.
     await null;
 
@@ -36,33 +36,55 @@ export const makeWhen = (
       if (seenPayloads.has(vowV0)) {
         throw Error('Vow resolution cycle detected');
       }
-      result = await basicE(vowV0)
-        .shorten()
-        .then(
-          res => {
-            seenPayloads.add(vowV0);
-            priorRetryValue = undefined;
-            return res;
-          },
-          e => {
-            const nextValue = isRetryableReason(e, priorRetryValue);
-            if (nextValue) {
-              // Shorten the same specimen to try again.
-              priorRetryValue = nextValue;
-              return result;
-            }
-            throw e;
-          },
-        );
+
+      try {
+        // Shorten the vow to the "next step", whether another vow or a final
+        // result.
+        const res = await basicE(vowV0).shorten();
+
+        // Prevent cycles in the resolution graph.
+        seenPayloads.add(vowV0);
+        priorRetryValue = undefined;
+        result = res;
+      } catch (e) {
+        const nextRetryValue = isRetryableReason(e, priorRetryValue);
+        if (!nextRetryValue) {
+          // Not a retry, so just reject with the reason.
+          throw e;
+        }
+
+        // Shorten the same specimen to try again.
+        priorRetryValue = nextRetryValue;
+      }
       // Advance to the next vow.
       payload = getVowPayload(result);
     }
 
     const unwrapped = /** @type {EUnwrap<T>} */ (result);
+    return unwrapped;
+  };
+
+  /**
+   * Shorten `specimenP` until we achieve a final result.
+   *
+   * Does not survive upgrade (even if specimenP is a durable Vow).
+   *
+   * @see {@link ../../README.md}
+   *
+   * @template T
+   * @template [TResult1=EUnwrap<T>]
+   * @template [TResult2=never]
+   * @param {T} specimenP value to unwrap
+   * @param {(value: EUnwrap<T>) => TResult1 | PromiseLike<TResult1>} [onFulfilled]
+   * @param {(reason: any) => TResult2 | PromiseLike<TResult2>} [onRejected]
+   * @returns {Promise<TResult1 | TResult2>}
+   */
+  const when = (specimenP, onFulfilled, onRejected) => {
+    const unwrapped = unwrap(specimenP);
 
     // We've extracted the final result.
     if (onFulfilled == null && onRejected == null) {
-      return /** @type {TResult1} */ (unwrapped);
+      return /** @type {Promise<TResult1>} */ (unwrapped);
     }
     return basicE.resolve(unwrapped).then(onFulfilled, onRejected);
   };

package/vat.js

@@ -7,7 +7,9 @@
 // @ts-check
 import { isUpgradeDisconnection } from '@agoric/internal/src/upgrade-api.js';
 import { makeHeapZone } from '@agoric/base-zone/heap.js';
-import { makeE, prepareVowTools as rawPrepareVowTools } from './src/index.js';
+
+import { prepareBasicVowTools } from './src/tools.js';
+import makeE from './src/E.js';
 
 /** @type {import('./src/types.js').IsRetryableReason} */
 const isRetryableReason = (reason, priorRetryValue) => {
@@ -28,16 +30,23 @@ export const defaultPowers = harden({
 /**
  * Produce SwingSet-compatible vowTools, with an arbitrary Zone type
  *
- * @type {typeof rawPrepareVowTools}
+ * @type {typeof prepareBasicVowTools}
+ */
+export const prepareSwingsetVowTools = (zone, powers = {}) =>
+  prepareBasicVowTools(zone, { ...defaultPowers, ...powers });
+harden(prepareSwingsetVowTools);
+
+/**
+ * Reexport as prepareVowTools, since that's the thing that people find easiest
+ * to reach.
  */
-export const prepareVowTools = (zone, powers = {}) =>
-  rawPrepareVowTools(zone, { ...defaultPowers, ...powers });
+export { prepareSwingsetVowTools as prepareVowTools };
 
 /**
  * `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());
+export const heapVowTools = prepareSwingsetVowTools(makeHeapZone());
 
 /**
  * A vow-shortening E, for use in vats that are not durable but receive vows.