feat(vow): a pattern for promises that survive upgrades

[michaelfig]

Closes: #8906

Description

Vows are a kind of "pseudo-promise" in that they are ocaps that can be made durable, and don't have a .then method so they won't be adopted by the platform Promise implementation.

The @agoric/vow module provides:

• a when(specimen): Promise<T> operator for returning a promise for the fulfilment of a specimen, including unwrapping any intermediate Vows. This operator is not durable-compatible.
• a watch(specimen, { onFulfilled, onRejected }): Vow<T> operator that registers possibly durable fulfilment and rejection handlers, and returns a durable Vow for the result of calling those handlers.
• makeVowKit(): { whenable, resolver: { resolve, reject } }

Security Considerations

Scaling Considerations

Documentation Considerations

Testing Considerations

Upgrade Considerations

[erights]

Are these all the files needed to create a well-formed package under agoric-sdk? In endo I use https://github.com/endojs/endo/blob/master/scripts/create-package.sh which starts my copying https://github.com/endojs/endo/tree/master/packages/skel

@kriskowal could agoric-sdk use its own copy of create-package.sh and skel for this purpose?

[erights]

Progress, but review far from done.

[erights]

I am finding it hard to review without already knowing concretely how you intend that it be used. There are neither inline comments nor any *.md files. There is the PR comment, which is certainly a great start!

I'll keep going on this review pass for awhile. But if I cannot figure it out despite my existing orientation, may others won't as well, until there is more explanatory text.

[erights]

Ok, I think I'm done enough for this pass. Will do another once I understand better.

[dckc]

ah... this looks like it demonstrates how to use the API

[dckc]

I think we need something that can go through endo interface guards.

false alarm