@agoric/swingset-liveslots 0.10.3-u13.0 → 0.10.3-u16.0

package/src/liveslots.js

@@ -33,7 +33,7 @@ const { details: X } = assert;
  * @param {*} syscall  Kernel syscall interface that the vat will have access to
  * @param {*} forVatID  Vat ID label, for use in debug diagnostics
  * @param {*} vatPowers
- * @param {import('./types').LiveSlotsOptions} liveSlotsOptions
+ * @param {import('./types.js').LiveSlotsOptions} liveSlotsOptions
  * @param {*} gcTools { WeakRef, FinalizationRegistry, waitUntilQuiescent, gcAndFinalize,
  *                      meterControl }
  * @param {Pick<Console, 'debug' | 'log' | 'info' | 'warn' | 'error'>} console
@@ -251,13 +251,10 @@ function build(
     const importsToRetire = new Set();
     const exportsToRetire = new Set();
     let doMore;
+    await null;
     do {
       doMore = false;
 
-      // Yes, we know this is an await inside a loop.  Too bad.  (Also, it's a
-      // `do {} while` loop, which means there's no conditional bypass of the
-      // await.)
-      // eslint-disable-next-line no-await-in-loop, @jessie.js/no-nested-await
       await gcTools.gcAndFinalize();
 
       // possiblyDeadSet contains a baseref for everything (Presences,
@@ -270,7 +267,6 @@ function build(
       const deadSet = new Set();
 
       for (const baseRef of possiblyDeadSet) {
-        // eslint-disable-next-line no-use-before-define
         if (slotToVal.has(baseRef)) {
           continue; // RAM pillar remains
         }
@@ -500,54 +496,6 @@ function build(
     return Remotable(iface);
   }
 
-  /**
-   * 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;
-    }
-  }
-
   // TODO: fix awkward non-orthogonality: allocateExportID() returns a number,
   // allocatePromiseID() returns a slot, registerPromise() uses the slot from
   // allocatePromiseID(), exportPassByPresence() generates a slot itself using
@@ -556,15 +504,18 @@ function build(
   // use a slot from the corresponding allocateX
 
   function allocateExportID() {
-    return allocateNextID('exportID');
+    // eslint-disable-next-line no-use-before-define
+    return vrm.allocateNextID('exportID');
   }
 
   function allocateCollectionID() {
-    return allocateNextID('collectionID');
+    // eslint-disable-next-line no-use-before-define
+    return vrm.allocateNextID('collectionID');
   }
 
   function allocatePromiseID() {
-    const promiseID = allocateNextID('promiseID');
+    // eslint-disable-next-line no-use-before-define
+    const promiseID = vrm.allocateNextID('promiseID');
     return makeVatSlot('promise', true, promiseID);
   }
 
@@ -612,7 +563,7 @@ function build(
     serializeBodyFormat: 'smallcaps',
     // TODO Temporary hack.
     // See https://github.com/Agoric/agoric-sdk/issues/2780
-    errorIdNum: 70000,
+    errorIdNum: 70_000,
     marshalSaveError: err =>
       // By sending this to `console.warn`, under cosmic-swingset this is
       // controlled by the `console` option given to makeLiveSlots.
@@ -759,9 +710,9 @@ function build(
       Fail`registerValue(${baseRef} should not receive individual facets`;
     slotToVal.set(baseRef, new WeakRef(val));
     if (valIsCohort) {
-      vrm.getFacetNames(id).forEach((name, index) => {
+      for (const [index, name] of vrm.getFacetNames(id).entries()) {
         valToSlot.set(val[name], `${baseRef}:${index}`);
-      });
+      }
     } else {
       valToSlot.set(val, baseRef);
     }
@@ -983,12 +934,20 @@ function build(
         return null;
       }
       syscall.resolve(resolutions);
-      resolutions.forEach(([_xvpid, _isReject, resolutionCD]) => {
-        resolutionCD.slots.forEach(vref => maybeNewVPIDs.add(vref));
-      });
-      resolutions.forEach(([xvpid]) => maybeNewVPIDs.delete(xvpid));
+      for (const resolution of resolutions) {
+        const [_xvpid, _isReject, resolutionCD] = resolution;
+        for (const vref of resolutionCD.slots) {
+          maybeNewVPIDs.add(vref);
+        }
+      }
+      for (const resolution of resolutions) {
+        const [xvpid] = resolution;
+        maybeNewVPIDs.delete(xvpid);
+      }
+    }
+    for (const newVPID of Array.from(maybeNewVPIDs).sort()) {
+      maybeExportPromise(newVPID);
     }
-    Array.from(maybeNewVPIDs).sort().forEach(maybeExportPromise);
 
     // ideally we'd wait until .then is called on p before subscribing, but
     // the current Promise API doesn't give us a way to discover this, so we
@@ -1190,13 +1149,21 @@ function build(
 
       const maybeNewVPIDs = new Set();
       // if we mention a vpid, we might need to track it
-      resolutions.forEach(([_xvpid, _isReject, resolutionCD]) => {
-        resolutionCD.slots.forEach(vref => maybeNewVPIDs.add(vref));
-      });
+      for (const resolution of resolutions) {
+        const [_xvpid, _isReject, resolutionCD] = resolution;
+        for (const vref of resolutionCD.slots) {
+          maybeNewVPIDs.add(vref);
+        }
+      }
       // but not if we just resolved it (including the primary)
-      resolutions.forEach(([xvpid]) => maybeNewVPIDs.delete(xvpid));
+      for (const resolution of resolutions) {
+        const [xvpid] = resolution;
+        maybeNewVPIDs.delete(xvpid);
+      }
       // track everything that's left
-      Array.from(maybeNewVPIDs).sort().forEach(maybeExportPromise);
+      for (const newVPID of Array.from(maybeNewVPIDs).sort()) {
+        maybeExportPromise(newVPID);
+      }
 
       // only the primary can possibly be newly resolved
       unregisterUnreferencedVPID(vpid);
@@ -1254,11 +1221,11 @@ function build(
     // 'imports' is an exclusively-owned Set that holds all new
     // promise vpids, both resolved and unresolved
     const imports = finishCollectingPromiseImports();
-    retiredVPIDs.forEach(vpid => {
+    for (const vpid of retiredVPIDs) {
       unregisterUnreferencedVPID(vpid); // unregisters if not in vdata
       importedVPIDs.delete(vpid);
       imports.delete(vpid); // resolved, so don't subscribe()
-    });
+    }
     for (const vpid of Array.from(imports).sort()) {
       syscall.subscribe(vpid);
     }
@@ -1298,14 +1265,18 @@ function build(
 
   function retireExports(vrefs) {
     assert(Array.isArray(vrefs));
-    vrefs.forEach(retireOneExport);
+    for (const vref of vrefs) {
+      retireOneExport(vref);
+    }
   }
 
   function retireImports(vrefs) {
     assert(Array.isArray(vrefs));
     vrefs.map(vref => insistVatType('object', vref));
     vrefs.map(vref => assert(!parseVatSlot(vref).allocatedByVat));
-    vrefs.forEach(vrm.ceaseRecognition);
+    for (const vref of vrefs) {
+      vrm.ceaseRecognition(vref);
+    }
   }
 
   // TODO: when we add notifyForward, guard against cycles
@@ -1450,7 +1421,7 @@ function build(
     }
     harden(vpow);
 
-    initializeIDCounters();
+    vrm.initializeIDCounters();
     vom.initializeKindHandleKind();
     collectionManager.initializeStoreKindInfo();
 
@@ -1496,7 +1467,7 @@ function build(
   }
 
   /**
-   * @param {import('./types').VatDeliveryObject} delivery
+   * @param {import('./types.js').VatDeliveryObject} delivery
    * @returns {void | Promise<void>}
    */
   function dispatchToUserspace(delivery) {
@@ -1561,7 +1532,7 @@ function build(
   }
 
   /**
-   * @param { import('./types').SwingSetCapData } _disconnectObjectCapData
+   * @param { import('./types.js').SwingSetCapData } _disconnectObjectCapData
    * @returns {Promise<void>}
    */
   async function stopVat(_disconnectObjectCapData) {
@@ -1573,7 +1544,7 @@ function build(
    * dispatch has completed and user code has relinquished agency.
    */
   function afterDispatchActions() {
-    flushIDCounters();
+    vrm.flushIDCounters();
     collectionManager.flushSchemaCache();
     vom.flushStateCache();
   }
@@ -1613,7 +1584,7 @@ function build(
    * terminate the vat). Userspace should not be able to cause the delivery
    * to fail: only a bug in liveslots should trigger a failure.
    *
-   * @param {import('./types').VatDeliveryObject} delivery
+   * @param {import('./types.js').VatDeliveryObject} delivery
    * @returns {Promise<void>}
    */
   async function dispatch(delivery) {
@@ -1629,7 +1600,7 @@ function build(
       // *not* directly wait for the userspace function to complete, nor for
       // any promise it returns to fire.
       const p = Promise.resolve(delivery).then(unmeteredDispatch);
-      p.finally(() => (complete = true));
+      void p.finally(() => (complete = true));
 
       // Instead, we wait for userspace to become idle by draining the
       // promise queue. We clean up and then examine/return 'p' so any
@@ -1664,7 +1635,7 @@ function build(
  * @param {*} syscall  Kernel syscall interface that the vat will have access to
  * @param {*} forVatID  Vat ID label, for use in debug diagostics
  * @param {*} vatPowers
- * @param {import('./types').LiveSlotsOptions} liveSlotsOptions
+ * @param {import('./types.js').LiveSlotsOptions} liveSlotsOptions
  * @param {*} gcTools { WeakRef, FinalizationRegistry, waitUntilQuiescent }
  * @param {Pick<Console, 'debug' | 'log' | 'info' | 'warn' | 'error'>} [liveSlotsConsole]
  * @param {*} [buildVatNamespace]

package/src/message.js

@@ -3,7 +3,7 @@ import { insistCapData } from './capdata.js';
 
 /**
  * @typedef {{
- * methargs: import('./types').SwingSetCapData, // of [method, args]
+ * methargs: import('./types.js').SwingSetCapData, // of [method, args]
  * result: string | undefined | null,
  * }} Message
  */
@@ -32,7 +32,7 @@ export function insistMessage(message) {
 
 /**
  * @param {unknown} vdo
- * @returns {asserts vdo is VatDeliveryObject}
+ * @returns {asserts vdo is import('./types').VatDeliveryObject}
  */
 
 export function insistVatDeliveryObject(vdo) {
@@ -114,7 +114,7 @@ export function insistVatDeliveryResult(vdr) {
 
 /**
  * @param {unknown} vso
- * @returns {asserts vso is VatSyscallObject}
+ * @returns {asserts vso is import('./types').VatSyscallObject}
  */
 
 export function insistVatSyscallObject(vso) {
@@ -194,7 +194,7 @@ export function insistVatSyscallObject(vso) {
 
 /**
  * @param {unknown} vsr
- * @returns {asserts vsr is VatSyscallResult}
+ * @returns {asserts vsr is import('./types').VatSyscallResult}
  */
 
 export function insistVatSyscallResult(vsr) {

package/src/types.js

@@ -1,3 +1,6 @@
+// Ensure this is a module.
+export {};
+
 /**
  * @callback makeLiveSlots
  */
@@ -79,5 +82,8 @@
  *
  */
 
-// Ensure this is a module.
-export {};
+/**
+ * @template V fulfilled value
+ * @template {any[]} [A=unknown[]] arguments
+ * @typedef { {onFulfilled?: (value: V, ...args: A) => void, onRejected?: (reason: unknown, ...args: A) => void} } PromiseWatcher
+ */

package/src/vatDataTypes.d.ts

@@ -0,0 +1,271 @@
+/**
+ * @file Types for vat-data
+ *
+ * Facet is a single object with methods.
+ * Behavior is a description when defining a kind of what facets it will have.
+ * For the non-multi defineKind, there is just one facet so it doesn't have a key.
+ */
+import type {
+  MapStore,
+  SetStore,
+  StoreOptions,
+  WeakMapStore,
+  WeakSetStore,
+} from '@agoric/store';
+import type { Amplify, IsInstance, ReceivePower, StateShape } from '@endo/exo';
+import type { RemotableObject } from '@endo/pass-style';
+import type { InterfaceGuard, Pattern } from '@endo/patterns';
+import type { makeWatchedPromiseManager } from './watchedPromises.js';
+
+// TODO should be moved into @endo/patterns and eventually imported here
+// instead of this local definition.
+export type InterfaceGuardKit = Record<string, InterfaceGuard>;
+export type { MapStore, Pattern };
+
+// This needs `any` values.  If they were `unknown`, code that uses Baggage
+// would need explicit runtime checks or casts for every fetch, which is
+// onerous.
+export type Baggage = MapStore<string, any>;
+
+type WatchedPromisesManager = ReturnType<typeof makeWatchedPromiseManager>;
+
+type Tail<T extends any[]> = T extends [head: any, ...rest: infer Rest]
+  ? Rest
+  : [];
+
+// used to omit the 'context' parameter
+type OmitFirstArg<F> = F extends (x: any, ...args: infer P) => infer R
+  ? (...args: P) => R
+  : never;
+
+export type KindFacet<O> = RemotableObject & {
+  [K in keyof O]: OmitFirstArg<O[K]>; // omit the 'context' parameter
+};
+
+export type KindFacets<B> = {
+  [FacetKey in keyof B]: KindFacet<B[FacetKey]>;
+};
+
+export type KindContext<S, F> = { state: S; self: KindFacet<F> };
+export type MultiKindContext<S, B> = { state: S; facets: KindFacets<B> };
+
+export type PlusContext<C, M extends (...args: any[]) => any> = (
+  c: C,
+  ...args: Parameters<M>
+) => ReturnType<M>;
+
+export type FunctionsPlusContext<
+  C,
+  O extends Record<string, (...args: any[]) => any>,
+> = {
+  [K in keyof O]: PlusContext<C, O[K]>;
+};
+
+declare class DurableKindHandleClass {
+  private descriptionTag: string;
+}
+export type DurableKindHandle = DurableKindHandleClass;
+
+/**
+ * Grab bag of options that can be provided to `defineDurableKind` and its
+ * siblings. Not all options are meaningful in all contexts. See the
+ * doc-comments on each option.
+ */
+export type DefineKindOptions<C> = {
+  /**
+   * If provided, the `finish` function will be called after the instance is
+   * made and internally registered, but before it is returned. The finish
+   * function is to do any post-intantiation initialization that should be
+   * done before exposing the object to its clients.
+   */
+  finish?: (context: C) => void;
+
+  /**
+   * If provided, it describes the shape of all state records of instances
+   * of this kind.
+   */
+  stateShape?: StateShape;
+
+  /**
+   * If a `receiveAmplifier` function is provided to an exo class kit definition,
+   * it will be called with an `Amplify` function. If provided to the definition
+   * of a normal exo or exo class, the definition will throw, since only
+   * exo kits can be amplified.
+   * An `Amplify` function is a function that takes a facet instance of
+   * this class kit as an argument, in which case it will return the facets
+   * record, giving access to all the facet instances of the same cohort.
+   */
+  receiveAmplifier?: ReceivePower<Amplify>;
+
+  /**
+   * If a `receiveInstanceTester` function is provided, it will be called
+   * during the definition of the exo class or exo class kit with an
+   * `IsInstance` function. The first argument of `IsInstance`
+   * is the value to be tested. When it may be a facet instance of an
+   * exo class kit, the optional second argument, if provided, is
+   * a `facetName`. In that case, the function tests only if the first
+   * argument is an instance of that facet of the associated exo class kit.
+   */
+  receiveInstanceTester?: ReceivePower<IsInstance>;
+
+  // TODO properties above are identical to those in FarClassOptions.
+  // These are the only options that should be exposed by
+  // vat-data's public virtual/durable exo APIs. This DefineKindOptions
+  // should explicitly be a subtype, where the methods below are only for
+  // internal use, i.e., below the exo level.
+
+  /**
+   * As a kind option, intended for internal use only.
+   * Meaningful to `makeScalarBigMapStore` and its siblings. These maker
+   * fuctions will make either virtual or durable stores, depending on
+   * this flag. Defaults to off, making virtual but not durable collections.
+   *
+   * Generally, durable collections are provided with `provideDurableMapStore`
+   * and its sibling, which use this flag internally. If you do not make
+   * durable collections by other means, you can consider this as
+   * intended for internal use only.
+   */
+  durable?: boolean;
+
+  /**
+   * Intended for internal use only.
+   * Should the raw methods receive their `context` argument as their first
+   * argument or as their `this` binding? For `defineDurableKind` and its
+   * siblings (including `prepareSingleton`), this defaults to off, meaning that
+   * their behavior methods receive `context` as their first argument.
+   * `prepareExoClass` and its siblings (including `prepareExo`) use
+   * this flag internally to indicate that their methods receive `context`
+   * as their `this` binding.
+   */
+  thisfulMethods?: boolean;
+
+  /**
+   * Intended for internal use only.
+   * Only applicable if this is a class kind. A class kit kind should use
+   * `interfaceGuardKit` instead.
+   *
+   * If an `interfaceGuard` is provided, then the raw methods passed alongside
+   * it are wrapped by a function that first checks that this method's guard
+   * pattern is satisfied before calling the raw method.
+   *
+   * In `defineDurableKind` and its siblings, this defaults to `undefined`.
+   * Exo classes use this internally to protect their raw class methods
+   * using the provided interface.
+   * In absence, an exo is protected anyway, while a bare kind is
+   * not (detected by `!thisfulMethods`),
+   */
+  interfaceGuard?: InterfaceGuard;
+
+  /**
+   * Intended for internal use only.
+   * Only applicable if this is a class kit kind. A class kind should use
+   * `interfaceGuard` instead.
+   *
+   * If an `interfaceGuardKit` is provided, then each member of the
+   * interfaceGuardKit is used to guard the corresponding facet of the
+   * class kit.
+   *
+   * In `defineDurableKindMulti` and its siblings, this defaults to `undefined`.
+   * Exo class kits use this internally to protect their facets.
+   * In absence, an exo is protected anyway, while a bare kind is
+   * not (detected by `!thisfulMethods`),
+   */
+  interfaceGuardKit?: InterfaceGuardKit;
+};
+
+export type VatData = {
+  // virtual kinds
+  /** @deprecated Use defineVirtualExoClass instead */
+  defineKind: <P extends Array<any>, S, F>(
+    tag: string,
+    init: (...args: P) => S,
+    facet: F,
+    options?: DefineKindOptions<KindContext<S, F>>,
+  ) => (...args: P) => KindFacet<F>;
+
+  /** @deprecated Use defineVirtualExoClassKit instead */
+  defineKindMulti: <P extends Array<any>, S, B>(
+    tag: string,
+    init: (...args: P) => S,
+    behavior: B,
+    options?: DefineKindOptions<MultiKindContext<S, B>>,
+  ) => (...args: P) => KindFacets<B>;
+
+  // durable kinds
+  makeKindHandle: (descriptionTag: string) => DurableKindHandle;
+
+  /** @deprecated Use defineDurableExoClass instead */
+  defineDurableKind: <P extends Array<any>, S, F>(
+    kindHandle: DurableKindHandle,
+    init: (...args: P) => S,
+    facet: F,
+    options?: DefineKindOptions<KindContext<S, F>>,
+  ) => (...args: P) => KindFacet<F>;
+
+  /** @deprecated Use defineDurableExoClassKit instead */
+  defineDurableKindMulti: <P extends Array<any>, S, B>(
+    kindHandle: DurableKindHandle,
+    init: (...args: P) => S,
+    behavior: B,
+    options?: DefineKindOptions<MultiKindContext<S, B>>,
+  ) => (...args: P) => KindFacets<B>;
+
+  providePromiseWatcher: WatchedPromisesManager['providePromiseWatcher'];
+  watchPromise: WatchedPromisesManager['watchPromise'];
+
+  makeScalarBigMapStore: <K, V>(
+    label: string,
+    options?: StoreOptions,
+  ) => MapStore<K, V>;
+  makeScalarBigWeakMapStore: <K, V>(
+    label: string,
+    options?: StoreOptions,
+  ) => WeakMapStore<K, V>;
+
+  makeScalarBigSetStore: <K>(
+    label: string,
+    options?: StoreOptions,
+  ) => SetStore<K>;
+  makeScalarBigWeakSetStore: <K>(
+    label: string,
+    options?: StoreOptions,
+  ) => WeakSetStore<K>;
+  canBeDurable: (specimen: unknown) => boolean;
+};
+
+// The JSDoc is repeated here and at the function definition so it appears
+// in IDEs where it's used, regardless of type resolution.
+export interface PickFacet {
+  /**
+   * When making a multi-facet kind, it's common to pick one facet to
+   * expose. E.g.,
+   *
+   *     const makeFoo = (a, b, c, d) => makeFooBase(a, b, c, d).self;
+   *
+   * This helper reduces the duplication:
+   *
+   *     const makeFoo = pickFacet(makeFooBase, 'self');
+   */
+  <M extends (...args: any[]) => any, F extends keyof ReturnType<M>>(
+    maker: M,
+    facetName: F,
+  ): (...args: Parameters<M>) => ReturnType<M>[F];
+}
+
+/** @deprecated Use prepareExoClass instead */
+export type PrepareKind = <P extends Array<any>, S, F>(
+  baggage: Baggage,
+  tag: string,
+  init: (...args: P) => S,
+  facet: F,
+  options?: DefineKindOptions<KindContext<S, F>>,
+) => (...args: P) => KindFacet<F>;
+
+/** @deprecated Use prepareExoClassKit instead */
+export type PrepareKindMulti = <P extends Array<any>, S, B>(
+  baggage: Baggage,
+  tag: string,
+  init: (...args: P) => S,
+  behavior: B,
+  options?: DefineKindOptions<MultiKindContext<S, B>>,
+) => (...args: P) => KindFacets<B>;

package/src/vatDataTypes.js

@@ -0,0 +1,2 @@
+// Empty JS file to correspond with vatDataTypes.d.ts
+export {};

package/src/vatstore-iterators.js

@@ -18,6 +18,7 @@ export function* enumerateKeysStartEnd(syscall, start, end, checkF) {
     dbKey = syscall.vatstoreGetNextKey(dbKey);
   }
 }
+harden(enumerateKeysStartEnd);
 
 // return an iterator of all existing keys that start with 'prefix'
 // (excluding the prefix itself)
@@ -32,6 +33,7 @@ export function* enumerateKeysWithPrefix(syscall, prefix) {
     yield key;
   }
 }
+harden(enumerateKeysWithPrefix);
 
 export function prefixedKeysExist(syscall, prefix) {
   const nextKey = syscall.vatstoreGetNextKey(prefix);