From 05eb6f0f15c6f3a775f2ee48e895d4d717a85d78 Mon Sep 17 00:00:00 2001
From: Michael FIG <mfig@agoric.com>
Date: Wed, 21 Aug 2024 12:56:41 -0600
Subject: [PATCH] docs(vow): update for the current implementation

---
 packages/vow/README.md | 32 +++++++++++++++++++-------------
 1 file changed, 19 insertions(+), 13 deletions(-)

diff --git a/packages/vow/README.md b/packages/vow/README.md
index b34dc1db902a..da4b8d34de3d 100644
--- a/packages/vow/README.md
+++ b/packages/vow/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;