@agoric/swingset-liveslots 0.10.3-other-dev-8f8782b.0 → 0.10.3-other-dev-fbe72e7.0.fbe72e7

package/src/virtualReferences.js

@@ -1,6 +1,6 @@
-/* eslint-disable no-use-before-define, jsdoc/require-returns-type */
+/* eslint-disable jsdoc/require-returns-type */
 
-import { assert, Fail } from '@agoric/assert';
+import { assert, Fail } from '@endo/errors';
 import { Nat } from '@endo/nat';
 import { parseVatSlot } from './parseVatSlots.js';
 import {
@@ -290,7 +290,10 @@ export function makeVirtualReferenceManager(
    */
   function isDurable(vref) {
     const { type, id, virtual, durable, allocatedByVat } = parseVatSlot(vref);
-    if (relaxDurabilityRules) {
+    if (type === 'promise') {
+      // promises are not durable even if `relaxDurabilityRules === true`
+      return false;
+    } else if (relaxDurabilityRules) {
       // we'll pretend an object is durable if running with relaxed rules
       return true;
     } else if (type === 'device') {
@@ -497,26 +500,51 @@ export function makeVirtualReferenceManager(
   }
 
   /**
-   * A vref is "recognizable" when it is used as the key of a weak Map
-   * or Set: that Map/Set can be used to query whether a future
-   * specimen matches the original or not, without holding onto the
-   * original.
+   * A vref is "recognizable" when it is used as the key of a weak
+   * collection, like a virtual/durable WeakMapStore or WeakSetStore,
+   * or the ephemeral voAwareWeakMap/Set that we impose upon userspace
+   * as "WeakMap/WeakSet". The collection can be used to query whether
+   * a future specimen matches the original or not, without holding
+   * onto the original.
+   *
+   * We need "recognition records" to map from the vref to the
+   * collection that can recognize it. When the vref is retired, we
+   * use the record to find all the collections from which we need to
+   * delete entries, so we can release the matching values. This might
+   * happen because the vref was for a Presence and the kernel just
+   * told us the upstream vat has deleted it (dispatch.retireImports),
+   * or because it was for a locally-managed object (an ephemeral
+   * Remotable or a virtual/durable Representative) and we decided to
+   * delete it.
+   *
+   * The virtual/durable collections track their "recognition records"
+   * in the vatstore, in keys like "vom.ir.${vref}|${collectionID}".
+   * These records do not contribute to our RAM usage.
+   *
+   * voAwareWeakMap and voAwareWeakSet store their recognition records
+   * in RAM, using this Map named 'vrefRecognizers'. Each key is a
+   * vref, and the value is a Set of recognizers. Each recognizer is
+   * the internal 'virtualObjectMap' in which the collection maps from
+   * vref to value. These in-RAM collections only use virtualObjectMap
+   * to track Presence-style (imports) and Representative-style
+   * (virtual/durable) vrefs: any Remotable-style keys are stored in
+   * the collection's internal (real) WeakMap under the Remotable
+   * object itself (because the engine handles the bookkeeping, and
+   * there is no virtual data in the value that we need to clean up at
+   * deletion time).
    *
-   * This 'vrefRecognizers' is a Map from those vrefs to the set of
-   * recognizing weak collections, for virtual keys and non-virtual
-   * collections. Specifically, the vrefs correspond to imported
-   * Presences or virtual-object Representatives (Remotables do not
-   * participate: they are keyed by the actual Remotable object, not
-   * its vref). The collections are either a VirtualObjectAwareWeakMap
-   * or a VirtualObjectAwareWeakSet. We remove the entry when the key
-   * is removed from the collection, and when the entire collection is
-   * deleted.
+   * Each voAwareWeakMap/Set must have a distinct recognizer, so we
+   * can remove the key from the right ones. The recognizer is held
+   * strongly by the recognition record, so it must not be the
+   * voAwareWeakMap/Set itself (which would inhibit GC).
    *
-   * It is critical that each collection have exactly one recognizer that is
-   * unique to that collection, because the recognizers themselves will be
-   * tracked by their object identities, but the recognizer cannot be the
-   * collection itself else it would prevent the collection from being garbage
-   * collected.
+   * When an individual entry is deleted from the weak collection, we
+   * must also delete the recognition record. When the collection
+   * itself is deleted (i.e. because nothing was referencing it), we
+   * must both delete all recognition records and also notify the
+   * kernel about any Presence-style vrefs that we can no longer
+   * recognize (syscall.retireImports). The kernel doesn't care about
+   * Remotable- or Representative- style vrefs, only the imports.
    *
    * TODO: all the "recognizers" in principle could be, and probably should be,
    * reduced to deleter functions.  However, since the VirtualObjectAware
@@ -532,14 +560,24 @@ export function makeVirtualReferenceManager(
   /** @type {Map<string, Set<Recognizer>>} */
   const vrefRecognizers = new Map();
 
+  /**
+   * @param {*} value  The vref-bearing object used as the collection key
+   * @param {string|Recognizer} recognizer  The collectionID or virtualObjectMap for the collection
+   * @param {boolean} [recognizerIsVirtual]  true for virtual/durable Stores, false for voAwareWeakMap/Set
+   */
   function addRecognizableValue(value, recognizer, recognizerIsVirtual) {
     const vref = getSlotForVal(value);
     if (vref) {
       const { type, allocatedByVat, virtual, durable } = parseVatSlot(vref);
-      if (type === 'object' && (!allocatedByVat || virtual || durable)) {
+      if (type === 'object') {
+        // recognizerSet (voAwareWeakMap/Set) doesn't track Remotables
+        const notRemotable = !allocatedByVat || virtual || durable;
+
         if (recognizerIsVirtual) {
+          assert.typeof(recognizer, 'string');
           syscall.vatstoreSet(`vom.ir.${vref}|${recognizer}`, '1');
-        } else {
+        } else if (notRemotable) {
+          assert.typeof(recognizer, 'object');
           let recognizerSet = vrefRecognizers.get(vref);
           if (!recognizerSet) {
             recognizerSet = new Set();
@@ -551,18 +589,33 @@ export function makeVirtualReferenceManager(
     }
   }
 
+  /**
+   * @param {string} vref  The vref or the object used as the collection key
+   * @param {string|Recognizer} recognizer  The collectionID or virtualObjectMap for the collection
+   * @param {boolean} [recognizerIsVirtual]  true for virtual/durable Stores, false for voAwareWeakMap/Set
+   */
   function removeRecognizableVref(vref, recognizer, recognizerIsVirtual) {
     const { type, allocatedByVat, virtual, durable } = parseVatSlot(vref);
-    if (type === 'object' && (!allocatedByVat || virtual || durable)) {
+    if (type === 'object') {
+      // addToPossiblyDeadSet only needs Presence-style vrefs
+      const isPresence = !allocatedByVat;
+      // recognizerSet (voAwareWeakMap/Set) doesn't track Remotables
+      const notRemotable = !allocatedByVat || virtual || durable;
+
       if (recognizerIsVirtual) {
+        assert.typeof(recognizer, 'string');
         syscall.vatstoreDelete(`vom.ir.${vref}|${recognizer}`);
-      } else {
+        if (isPresence) {
+          addToPossiblyRetiredSet(vref);
+        }
+      } else if (notRemotable) {
+        assert.typeof(recognizer, 'object');
         const recognizerSet = vrefRecognizers.get(vref);
         assert(recognizerSet && recognizerSet.has(recognizer));
         recognizerSet.delete(recognizer);
         if (recognizerSet.size === 0) {
           vrefRecognizers.delete(vref);
-          if (!allocatedByVat) {
+          if (isPresence) {
             addToPossiblyRetiredSet(vref);
           }
         }
@@ -570,6 +623,11 @@ export function makeVirtualReferenceManager(
     }
   }
 
+  /**
+   * @param {*} value  The vref-bearing object used as the collection key
+   * @param {string|Recognizer} recognizer  The collectionID or virtualObjectMap for the collection
+   * @param {boolean} [recognizerIsVirtual]  true for virtual/durable Stores, false for voAwareWeakMap/Set
+   */
   function removeRecognizableValue(value, recognizer, recognizerIsVirtual) {
     const vref = getSlotForVal(value);
     if (vref) {
@@ -682,6 +740,54 @@ export function makeVirtualReferenceManager(
     return size;
   }
 
+  /**
+   * Counters to track the next number for various categories of allocation.
+   * `exportID` starts at 1 because 'o+0' is always automatically
+   * pre-assigned to the root object.
+   * `promiseID` starts at 5 as a very minor aid to debugging: when puzzling
+   * over trace logs and the like, it helps for the numbers in various species
+   * of IDs that are jumbled together to be a little out of sync and thus a
+   * little less similar to each other.
+   */
+  const initialIDCounters = { exportID: 1, collectionID: 1, promiseID: 5 };
+  /** @type {Record<string, number>} */
+  let idCounters;
+  let idCountersAreDirty = false;
+
+  function initializeIDCounters() {
+    if (!idCounters) {
+      // the saved value might be missing, or from an older liveslots
+      // (with fewer counters), so merge it with our initial values
+      const saved = JSON.parse(syscall.vatstoreGet('idCounters') || '{}');
+      idCounters = { ...initialIDCounters, ...saved };
+      idCountersAreDirty = true;
+    }
+  }
+
+  function allocateNextID(name) {
+    if (!idCounters) {
+      // Normally `initializeIDCounters` would be called from startVat, but some
+      // tests bypass that so this is a backstop.  Note that the invocation from
+      // startVat is there to make vatStore access patterns a bit more
+      // consistent from one vat to another, principally as a confusion
+      // reduction measure in service of debugging; it is not a correctness
+      // issue.
+      initializeIDCounters();
+    }
+    const result = idCounters[name];
+    result !== undefined || Fail`unknown idCounters[${name}]`;
+    idCounters[name] += 1;
+    idCountersAreDirty = true;
+    return result;
+  }
+
+  function flushIDCounters() {
+    if (idCountersAreDirty) {
+      syscall.vatstoreSet('idCounters', JSON.stringify(idCounters));
+      idCountersAreDirty = false;
+    }
+  }
+
   const testHooks = {
     getReachableRefCount,
     countCollectionsForWeakKey,
@@ -726,6 +832,9 @@ export function makeVirtualReferenceManager(
     ceaseRecognition,
     setDeleteCollectionEntry,
     getRetentionStats,
+    initializeIDCounters,
+    allocateNextID,
+    flushIDCounters,
     testHooks,
   });
 }

package/src/vpid-tracking.md

@@ -0,0 +1,92 @@
+# Promise/VPID Management in Liveslots
+
+Kernels and vats communicate about promises by referring to their VPIDs: vat(-centric) promise IDs. These are strings like `p+12` and `p-23`. Like VOIDs (object IDs), the plus/minus sign indicates which side of the boundary allocated the number (`p+12` and `o+12` are allocated by the vat, `p-13` and `o-13` are allocated by the kernel). But where the object ID sign also indicates which side "owns" the object (i.e. where the behavior lives), the promise ID sign is generally irrelevant.
+
+Instead, we care about which side holds the resolution authority for a promise (referred to as being its **decider**). This is not indicated by the VPID sign, and in fact is not necessarily static. Liveslots does not currently have any mechanism to allow one promise to be forwarded to another, but if it acquires this some day, then the decider of a promise could shift from kernel to vat to kernel again before it finally gets resolved. And there *are* sequences that allow a vat to receive a reference to a promise in method arguments before receiving a message whose result promise uses that same VPID (e.g., `p1 = p2~.foo(); x~.bar(p1)`, then someone resolves `p2` to `x`. Consider also tildot-free code like `{ promise: p1, resolve: resolveP1 } = makePromiseKit(); p2 = E(p1).push('queued'); await E(observer).push(p2); resolveP1(observer);` with an observer whose `push` returns a prompt response). In such cases, the decider is initially the kernel but that authority is transferred to a vat later.
+
+Each Promise starts out in the "unresolved" state, then later transitions irrevocably to the "resolved" state. Liveslots frequently (but not always) pays attention to this transition by calling `then` to attach fulfillment/rejection settlement callbacks. To handle resolution cycles, liveslots remembers the resolution of old promises in a `WeakMap` for as long as the Promise exists. Consequently, for liveslots' purposes, every Promise is either resolved (a callback has fired and liveslots remembers the settlement), or unresolved (liveslots has not yet seen a resolution that settles it).
+
+There are roughly four ways that liveslots might become aware of a promise:
+
+* serialization: a Promise instance is serialized, either for the arguments of an outbound `syscall.send` or `syscall.resolve`, the argument of `watchPromise()`, or to be stored into virtualized data (e.g. `bigMapStore.set(key, promise)`, or assignment to a property of a virtual object)
+* creation for outbound result: liveslots allocates a VPID for the `result` of an outbound `syscall.send`, and creates a new Promise instance to give back to userspace
+* deserialization: the arguments of an inbound `dispatch.deliver` or `dispatch.notify` are deserialized, and a new Promise instance is created
+* inbound result: the kernel-allocated `result` VPID of an inbound `dispatch.deliver` is associated with the Promise we get back from `HandledPromise.applyMethod`
+
+A Promise may be associated with a VPID even though the kernel does not know about it (i.e. the VPID is not in the kernel's c-list for that vat). This can occur when a Promise is stored into virtual data without also being sent to (or received from) the kernel, although note that every Promise associated with a durable promise watcher _is_ sent to the kernel so it can be rejected during vat upgrade. A Promise can also be resolved but still referenced in vdata and forgotten by the kernel (the kernel's knowledge is temporary; it retires VPIDs from c-lists upon `syscall.resolve` or `dispatch.notify` as appropriate). So a VPID might start out stored only in vdata, then get sent to the kernel, then get resolved, leaving it solely in vdata once more.
+
+Each unresolved VPID has a decider: either the kernel or a vat. It can remain unresolved for arbitrarily long, but becomes resolved by the first of the following events:
+
+* if liveslots learns about local resolution of the corresponding Promise by userspace, then liveslots will perform a `syscall.resolve()` (prompting 'notify' deliveries to other subscribed vats)
+* if liveslots learns about resolution by inbound notify, then liveslots will unregister it as necessary and inform userspace of the resolution
+* if the vat is terminated, the kernel internally rejects all remaining vat-decided KPIDs without involving the vat
+* if the vat is upgraded, each of those terminate-associated rejections is followed by a 'notify' delivery to the new incarnation
+
+Liveslots tracks promises in the following data structures:
+
+* `slotToVal` / `valToSlot` : these manage *registration*, the mapping from VPID to Promise and vice versa. These also register objects (Presences, Remotables, and Representatives) to/from VOIDs, and device nodes.
+  * to support GC of objects, `slotToVal.get(vref)` is a WeakRef, and `valToSlot` is a WeakMap
+  * liveslots uses independent strong references to maintain object/promise lifetimes
+* `exportedVPIDs`: a `Map<VPID, Promise>`: all Promises currently known to the kernel and decided by the vat
+* `importedVPIDs`: a `Map<VPID, PromiseKit>`: all Promises currently known to the kernel and decided by the kernel
+* `remotableRefCounts`: a `Map<Object|Promise, Number>`: all Promises (and Remotables) referenced by virtual data
+
+The kernel's c-list for a vat contains all VPIDs in `exportedVPIDs` and `importedVPIDs`. The vat is the decider for `exportedVPIDs`, while the kernel is the decider for `importedVPIDs`. For every VPID in `exportedVPIDs`, we've used `then` on the Promise instance to arrange for a `syscall.resolve` when it settles (becomes fulfilled or rejected). For every VPID key of the `importedVPIDs` Map, the corresponding value is a `[resolve, reject]` "**pRec**", so one of the functions can be called during `dispatch.notify`. Every VPID in `slotToVal` is either in `exportedVPIDs` but not `importedVPIDs`, `importedVPIDs` but not `exportedVPIDs`, or neither.
+
+If a VPID in `importedVPIDs` is resolved (by the kernel, via `dispatch.notify`), the VPID is removed from `importedVPIDs`. If a VPID in `exportedVPIDs` is resolved (by the vat, i.e. liveslots observes invocation of a previously-added settlement callback), liveslots invokes `syscall.resolve` and removes the VPID from `exportedVPIDs`. The c-list for a vat will not contain a VPID for any resolved promise.
+
+The `slotToVal`/`valToSlot` registration must remain until all of the following are true:
+
+* the kernel is no longer aware of the VPID
+* the Promise is not present in any virtual data
+* the promise is not being watched by a `promiseWatcher`.
+
+If the registration were to be lost while any of the above conditions were still true, a replacement Promise might be created while the original was still around, causing confusion.
+
+## Maintaining Strong References
+
+Remember that the `slotToVal` registration uses a WeakRef, so being registered there does not keep the Promise object alive.
+ 
+`exportedVPIDs` and `importedVPIDs` keep their Promise alive in their value. vdata keeps it alive through the key of `remotableRefCounts`. `promiseWatcher` uses an internal `ScalarBigMapStore` to keep the Promise alive.
+
+## Promise/VPID Management Algorithm
+
+* When a Promise is first serialized (it appears in `convertValToSlot`), a VPID is assigned and the VPID/Promise mapping is registered in `valToSlot`/`slotToVal`
+  * at this point, there is not yet a strong reference to the Promise
+* When a VPID appears in the serialized arguments of `syscall.send` or `syscall.resolve`:
+  * if the VPID already exists in `exportedVPIDs` or `importedVPIDs`: do nothing
+  * else: use `followForKernel` to add the VPID to `exportedVPIDs` and attach `.then(onFulfill, onReject)` callbacks that will map fulfillment/rejection to `syscall.resolve()`
+* When a `followForKernel` settlement callback is executed:
+  * do `syscall.resolve()`
+  * remove from `exportedVPIDs`
+  * if `remotableRefCounts` reports 0 references: unregister from `valToSlot`/`slotToVal`
+* When the kernel delivers a `dispatch.notify`:
+  * retrieve the `[resolve, reject]` pRec from `importedVPIDs`
+  * invoke the appropriate function with the deserialized argument
+  * if `remotableRefCounts` reports 0 references: unregister from `valToSlot`/`slotToVal`
+* When the vdata refcount for a VPID drops to zero:
+  * if the VPID still exists in `exportedVPIDs` or `importedVPIDs`: do nothing
+  * else: unregister from `valToSlot`/`slotToVal`
+* When a new VPID is deserialized (it appears in `convertSlotToVal`), this must be the arguments of a delivery (not vdata)
+  * use `makePipelinablePromise` to create a HandledPromise for the VPID
+  * add the Promise and its `resolve`/`reject` pair to `importedVPIDs`
+  * register the Promise in `valToSlot`/`slotToVal`
+  * use `syscall.subscribe` to request a `dispatch.notify` delivery when the kernel resolves this promise
+* When a VPID appears as the `result` of an outbound `syscall.send`: (_note overlap with the preceding_)
+  * use `allocateVPID` to allocate a new VPID
+  * use `makePipelinablePromise` to create a HandledPromise for the VPID
+  * add the Promise and its `resolve`/`reject` pair to `importedVPIDs`
+  * register the Promise in `valToSlot`/`slotToVal`
+  * use `syscall.subscribe` to request a `dispatch.notify` delivery when the kernel resolves this promise
+* When a VPID appears as the `result` of an inbound `dispatch.deliver`, the vat is responsible for deciding it:
+  * construct a promise `res` to capture the userspace-provided result
+  * if the VPID is present in `importedVPIDs`: retrieve the `[resolve, reject]` pRec and use `resolve(res)` to forward eventual settlement of `res` to settlement of the previously-imported promise, then remove the VPID from `importedVPIDs`
+  * else: register marshaller association between the VPID and `res`
+  * in either case, use `followForKernel` to add the VPID to `exportedVPIDs` and attach `.then(onFulfill, onReject)` callbacks that will map fulfillment/rejection to `syscall.resolve()`
+
+
+If the serialization is for storage in virtual data, the act of storing the VPID will add the Promise to `remotableRefCounts`, which maintains a strong reference for as long as the VPID is held. When it is removed from virtual data (or the object/collection is deleted), the refcount will be decremented. When the refcount drops to zero, we perform the `exportedVPIDs`/`importedVPIDs` check and then maybe unregister the promise.
+
+If the serialization is for the arguments of an outbound `syscall.send` or `syscall.resolve` (or `syscall.callNow`, or `syscall.exit`), the VPID will be added to `exportedVPIDs`.
+
+If the *un*serialization occurred when processing the arguments of an *in*bound `dispatch.deliver` or `dispatch.notify`, the VPID (and the "promise kit" trio of Promise, `resolve`, and `reject`) will be stored in `importedVPIDs`.

package/src/watchedPromises.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @template V
+ * @template {any[]} [A=unknown[]]
+ * @typedef {[watcher: import('./types.js').PromiseWatcher<V, A>, ...args: A]} PromiseWatcherTuple
+ */
+/**
+ * @param {object} options
+ * @param {*} options.syscall
+ * @param {import('./virtualReferences.js').VirtualReferenceManager} options.vrm
+ * @param {import('./virtualObjectManager.js').VirtualObjectManager} options.vom
+ * @param {*} options.collectionManager
+ * @param {import('@endo/marshal').ConvertValToSlot<any>} options.convertValToSlot
+ * @param {import('@endo/marshal').ConvertSlotToVal<any>} options.convertSlotToVal
+ * @param {(vref: any) => boolean} options.maybeExportPromise
+ */
+export function makeWatchedPromiseManager({ syscall, vrm, vom, collectionManager, convertValToSlot, convertSlotToVal, maybeExportPromise, }: {
+    syscall: any;
+    vrm: import("./virtualReferences.js").VirtualReferenceManager;
+    vom: import("./virtualObjectManager.js").VirtualObjectManager;
+    collectionManager: any;
+    convertValToSlot: import("@endo/marshal").ConvertValToSlot<any>;
+    convertSlotToVal: import("@endo/marshal").ConvertSlotToVal<any>;
+    maybeExportPromise: (vref: any) => boolean;
+}): {
+    preparePromiseWatcherTables: () => void;
+    loadWatchedPromiseTable: (revivePromise: (vref: any) => Promise<any>) => void;
+    providePromiseWatcher: <V, A extends any[]>(kindHandle: import("./vatDataTypes.js").DurableKindHandle, fulfillHandler?: (value: V, ...args: A) => void, rejectHandler?: (reason: any, ...args: A) => void) => import("./types.js").PromiseWatcher<V, A>;
+    watchPromise: <P extends Promise<any>, A extends any[]>(p: P, watcher: import("./types.js").PromiseWatcher<Awaited<P>, A>, ...args: A) => void;
+};
+export type PromiseWatcherTuple<V, A extends any[] = unknown[]> = [watcher: import("./types.js").PromiseWatcher<V, A>, ...args: A];
+//# sourceMappingURL=watchedPromises.d.ts.map

package/src/watchedPromises.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchedPromises.d.ts","sourceRoot":"","sources":["watchedPromises.js"],"names":[],"mappings":"AASA;;;;GAIG;AAEH;;;;;;;;;GASG;AACH,6IARG;IAAmB,OAAO,EAAlB,GAAC;IACiE,GAAG,EAArE,OAAO,wBAAwB,EAAE,uBAAuB;IACU,GAAG,EAArE,OAAO,2BAA2B,EAAE,oBAAoB;IAC7C,iBAAiB,EAA5B,GAAC;IACsD,gBAAgB,EAAvE,OAAO,eAAe,EAAE,gBAAgB,CAAC,GAAG,CAAC;IACU,gBAAgB,EAAvE,OAAO,eAAe,EAAE,gBAAgB,CAAC,GAAG,CAAC;IACb,kBAAkB,EAAlD,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO;CAChC;;6CA+GY,CAAC,IAAI,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,CAAC,KACzB,IAAI;4BAiBJ,CAAC,EACO,CAAC,SAAR,GAAG,EAAG,cACT,OAAO,mBAAmB,EAAE,iBAAiB,mBAC7C,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,kBAC9B,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,KAC/B,OAAO,YAAY,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC;mBAmC3C,CAAC,SAAS,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,SAAS,GAAG,EAAE,KAAK,CAAC,WAAW,OAAO,YAAY,EAAE,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,KAAK,IAAI;EAoE3I;gCA3PY,CAAC,EACQ,CAAC,SAAT,GAAG,EAAG,gBACP,CAAC,OAAO,EAAE,OAAO,YAAY,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC"}

package/src/watchedPromises.js

@@ -1,11 +1,18 @@
+// @ts-check
 // no-lonely-if is a stupid rule that really should be disabled globally
 /* eslint-disable no-lonely-if */
 
-import { assert } from '@agoric/assert';
-import { initEmpty, M } from '@agoric/store';
+import { Fail, assert } from '@endo/errors';
 import { E } from '@endo/eventual-send';
+import { initEmpty, M } from '@agoric/store';
 import { parseVatSlot } from './parseVatSlots.js';
 
+/**
+ * @template V
+ * @template {any[]} [A=unknown[]]
+ * @typedef {[watcher: import('./types.js').PromiseWatcher<V, A>, ...args: A]} PromiseWatcherTuple
+ */
+
 /**
  * @param {object} options
  * @param {*} options.syscall
@@ -28,21 +35,31 @@ export function makeWatchedPromiseManager({
   const { makeScalarBigMapStore } = collectionManager;
   const { defineDurableKind } = vom;
 
-  // virtual Store (not durable) mapping vpid to Promise objects, to
-  // maintain the slotToVal registration until resolution. Without
-  // this, slotToVal would forget local Promises that aren't exported.
-  let promiseRegistrations;
+  /**
+   * Track promises watched in `buildRootObject` so `loadWatchedPromiseTable`
+   * can differentiate them from promises watched in a previous incarnation.
+   *
+   * @type {Set<string> | null}
+   */
+  let buildRootObjectWatchedPromiseRefs;
 
-  // watched promises by vpid: each entry is an array of watches on the
-  // corresponding vpid; each of these is in turn an array of a watcher object
-  // and the arguments associated with it by `watchPromise`.
+  /**
+   * watched promises by vpid: each entry is an array of watches on the
+   * corresponding vpid; each of these is in turn an array of a watcher object
+   * and the arguments associated with it by `watchPromise`.
+   * @type {MapStore<string, PromiseWatcherTuple<unknown>[]>}
+   */
   let watchedPromiseTable;
 
-  // defined promise watcher objects indexed by kindHandle
+  /**
+   * defined promise watcher objects indexed by kindHandle
+   *
+   * @type {MapStore<import('./vatDataTypes.js').DurableKindHandle, import('./types.js').PromiseWatcher<unknown>>}
+   */
   let promiseWatcherByKindTable;
 
   function preparePromiseWatcherTables() {
-    promiseRegistrations = makeScalarBigMapStore('promiseRegistrations');
+    buildRootObjectWatchedPromiseRefs = new Set();
     let watcherTableID = syscall.vatstoreGet('watcherTableID');
     if (watcherTableID) {
       promiseWatcherByKindTable = convertSlotToVal(watcherTableID);
@@ -73,15 +90,21 @@ export function makeWatchedPromiseManager({
   }
 
   /**
-   *
-   * @param {Promise<unknown>} p
+   * @template T
+   * @param {Promise<T>} p
    * @param {string} vpid
+   * @returns {void}
    */
   function pseudoThen(p, vpid) {
+    /**
+     *
+     * @param {T} value
+     * @param {boolean} wasFulfilled
+     */
     function settle(value, wasFulfilled) {
       const watches = watchedPromiseTable.get(vpid);
       watchedPromiseTable.delete(vpid);
-      promiseRegistrations.delete(vpid);
+      buildRootObjectWatchedPromiseRefs?.delete(vpid);
       for (const watch of watches) {
         const [watcher, ...args] = watch;
         void Promise.resolve().then(() => {
@@ -115,26 +138,46 @@ export function makeWatchedPromiseManager({
    */
   function loadWatchedPromiseTable(revivePromise) {
     for (const vpid of watchedPromiseTable.keys()) {
+      if (buildRootObjectWatchedPromiseRefs?.has(vpid)) {
+        // We're only interested in reconnecting the promises from the previous
+        // incarnation. Any promise watched during buildRootObject would have
+        // already created a registration.
+        continue;
+      }
       const p = revivePromise(vpid);
-      promiseRegistrations.init(vpid, p);
       pseudoThen(p, vpid);
     }
+    buildRootObjectWatchedPromiseRefs = null;
   }
 
+  /**
+   * @template V
+   * @template {any[]} A]
+   * @param {import('./vatDataTypes.js').DurableKindHandle} kindHandle
+   * @param {(value: V, ...args: A) => void} fulfillHandler
+   * @param {(reason: any, ...args: A) => void} rejectHandler
+   * @returns {import('./types.js').PromiseWatcher<V, A>}
+   */
   function providePromiseWatcher(
     kindHandle,
-    fulfillHandler = x => x,
-    rejectHandler = x => {
-      throw x;
+    // @ts-expect-error xxx rest params in typedef
+    fulfillHandler = _value => {
+      // It's fine to not pass the value through since promise watchers are not chainable
+    },
+    // @ts-expect-error xxx rest params in typedef
+    rejectHandler = reason => {
+      // Replicate the unhandled rejection that would have happened if the
+      // watcher had not implemented an `onRejected` method. See `settle` above
+      throw reason;
     },
   ) {
     assert.typeof(fulfillHandler, 'function');
     assert.typeof(rejectHandler, 'function');
 
     const makeWatcher = defineDurableKind(kindHandle, initEmpty, {
-      // @ts-expect-error  TS is confused by the spread operator
+      /** @type {(context: unknown, res: V, ...args: A) => void} */
       onFulfilled: (_context, res, ...args) => fulfillHandler(res, ...args),
-      // @ts-expect-error
+      /** @type {(context: unknown, rej: unknown, ...args: A) => void} */
       onRejected: (_context, rej, ...args) => rejectHandler(rej, ...args),
     });
 
@@ -147,6 +190,9 @@ export function makeWatchedPromiseManager({
     }
   }
 
+  /**
+   * @type {<P extends Promise<any>, A extends any[]>(p: P, watcher: import('./types.js').PromiseWatcher<Awaited<P>, A>, ...args: A) => void}
+   */
   function watchPromise(p, watcher, ...args) {
     // The following wrapping defers setting up the promise watcher itself to a
     // later turn so that if the promise to be watched was the return value from
@@ -163,7 +209,10 @@ export function makeWatchedPromiseManager({
       const watcherVref = convertValToSlot(watcher);
       assert(watcherVref, 'invalid watcher');
       const { virtual, durable } = parseVatSlot(watcherVref);
-      assert(virtual || durable, 'promise watcher must be a virtual object');
+      virtual ||
+        durable ||
+        // separate line so easy to breakpoint on
+        Fail`promise watcher must be a virtual object`;
       if (watcher.onFulfilled) {
         assert.typeof(watcher.onFulfilled, 'function');
       }
@@ -185,13 +234,21 @@ export function makeWatchedPromiseManager({
       } else {
         watchedPromiseTable.init(vpid, harden([[watcher, ...args]]));
 
+        buildRootObjectWatchedPromiseRefs?.add(vpid);
+
+        // To avoid triggering
+        // https://github.com/Agoric/agoric-sdk/issues/10757 and
+        // preventing slotToVal cleanup, the `pseudoThen()` should
+        // precede `maybeExportPromise()`. This isn't foolproof, but
+        // does mitigate in advance of a proper fix. See #10756 for
+        // details of this particular mitigation, and #10757 for the
+        // deeper bug.
+        pseudoThen(p, vpid);
+
         // Ensure that this vat's promises are rejected at termination.
         if (maybeExportPromise(vpid)) {
           syscall.subscribe(vpid);
         }
-
-        promiseRegistrations.init(vpid, p);
-        pseudoThen(p, vpid);
       }
     });
   }

package/test/{test-baggage.js → baggage.test.js}

@@ -1,10 +1,9 @@
 import test from 'ava';
-import '@endo/init/debug.js';
 
 import { Far } from '@endo/marshal';
+import { kunser } from '@agoric/kmarshal';
 import { setupTestLiveslots } from './liveslots-helpers.js';
 import { vstr } from './util.js';
-import { kunser } from './kmarshal.js';
 import { parseVatSlot } from '../src/parseVatSlots.js';
 
 function buildRootObject(vatPowers, vatParameters, baggage) {

package/test/{test-cache.js → cache.test.js}

@@ -1,5 +1,4 @@
 import test from 'ava';
-import '@endo/init/debug.js';
 
 import { makeCache } from '../src/cache.js';