chore: Sync Endo versions (2024-05-07) (#9334)

This brings Agoric in sync with Endo versions
endojs/endo#2272 which covers a new `Passable`
type and improvements to `pass-style`, `patterns`, and `exo`. This
subsumes changes from #8774
necessary for integration.

Author: mergify[bot]

MAINTAINERS.md

@@ -264,8 +264,8 @@ From `origin/master`, begin a branch for syncing Endo.
 
 ```sh
 NOW=`date -u +%Y-%m-%d-%H-%M-%S`
-git checkout -b "$USER-sync-endo-$NOW" origin/endo-integration-master
-git rebase origin/master
+git checkout -b "$USER-sync-endo-$NOW"
+git rebase origin/integration-endo-master
 ```
 
 Use a helper script from the Endo repository to update the dependency versions
@@ -308,8 +308,6 @@ Increment the meter type in `packages/xsnap/api.js`:
 export const METER_TYPE = 'xs-meter-0';
 ```
 
-Be sure to also update `test/test-xs-perf.js` with the new meter version.
-
 ```sh
 cd packages/xsnap
 git add api.js

package.json

@@ -10,7 +10,7 @@
   "type": "module",
   "packageManager": "yarn@1.22.19",
   "devDependencies": {
-    "@endo/eslint-plugin": "^2.1.2",
+    "@endo/eslint-plugin": "^2.1.3",
     "@jessie.js/eslint-plugin": "^0.4.1",
     "@types/express": "^4.17.17",
     "@types/node": "^18.19.24",

packages/ERTP/package.json

@@ -44,16 +44,16 @@
     "@agoric/store": "^0.9.2",
     "@agoric/vat-data": "^0.5.2",
     "@agoric/zone": "^0.2.2",
-    "@endo/eventual-send": "^1.2.1",
-    "@endo/far": "^1.1.1",
-    "@endo/marshal": "^1.4.1",
-    "@endo/nat": "^5.0.6",
-    "@endo/patterns": "^1.3.1",
-    "@endo/promise-kit": "^1.1.1"
+    "@endo/eventual-send": "^1.2.2",
+    "@endo/far": "^1.1.2",
+    "@endo/marshal": "^1.5.0",
+    "@endo/nat": "^5.0.7",
+    "@endo/patterns": "^1.4.0",
+    "@endo/promise-kit": "^1.1.2"
   },
   "devDependencies": {
     "@agoric/swingset-vat": "^0.32.2",
-    "@endo/bundle-source": "^3.2.2",
+    "@endo/bundle-source": "^3.2.3",
     "@fast-check/ava": "^1.1.5",
     "ava": "^5.3.0",
     "tsd": "^0.30.7"
@@ -86,6 +86,6 @@
     "access": "public"
   },
   "typeCoverage": {
-    "atLeast": 90.62
+    "atLeast": 91.21
   }
 }

packages/ERTP/src/amountMath.js

@@ -6,7 +6,10 @@ import { setMathHelpers } from './mathHelpers/setMathHelpers.js';
 import { copySetMathHelpers } from './mathHelpers/copySetMathHelpers.js';
 import { copyBagMathHelpers } from './mathHelpers/copyBagMathHelpers.js';
 
-/** @import {Amount, AssetKind, AmountValue, AssetKindForValue, AssetValueForKind, Brand, MathHelpers} from './types.js' */
+/**
+ * @import {CopyBag, CopySet} from '@endo/patterns';
+ * @import {Amount, AssetKind, AmountValue, AssetKindForValue, AssetValueForKind, Brand, CopyBagAmount, CopySetAmount, MathHelpers, NatAmount, NatValue, SetAmount, SetValue} from './types.js';
+ */
 
 const { quote: q, Fail } = assert;
 
@@ -76,26 +79,19 @@ const helpers = {
   copyBag: copyBagMathHelpers,
 };
 
-/**
- * @template {AmountValue} V
- * @type {(value: V) => AssetKindForValue<V>}
- */
+/** @type {(value: unknown) => 'nat' | 'set' | 'copySet' | 'copyBag'} } */
 const assertValueGetAssetKind = value => {
   const passStyle = passStyleOf(value);
   if (passStyle === 'bigint') {
-    // @ts-expect-error cast
     return 'nat';
   }
   if (passStyle === 'copyArray') {
-    // @ts-expect-error cast
     return 'set';
   }
   if (matches(value, M.set())) {
-    // @ts-expect-error cast
     return 'copySet';
   }
   if (matches(value, M.bag())) {
-    // @ts-expect-error cast
     return 'copyBag';
   }
   // TODO This isn't quite the right error message, in case valuePassStyle
@@ -113,7 +109,7 @@ const assertValueGetAssetKind = value => {
  *
  * Made available only for testing, but it is harmless for other uses.
  *
- * @template {AmountValue} V
+ * @template V
  * @param {V} value
  * @returns {MathHelpers<V>}
  */
@@ -198,29 +194,44 @@ const isGTE = (leftAmount, rightAmount, brand = undefined) => {
  * the abstract right to participate in a particular exchange.
  */
 const AmountMath = {
+  // TODO use overloading to handle when Brand has an AssetKind and when it doesn't.
+  // a AmountForValue utility could help DRY those cases.
   /**
    * Make an amount from a value by adding the brand.
    *
-   * @template {AssetKind} K
-   * @param {Brand<K>} brand
-   * @param {AssetValueForKind<K>} allegedValue
-   * @returns {Amount<K>}
+   * Does not verify that the Brand's AssetKind matches the value's.
+   *
+   * @template {Brand} B
+   * @template {NatValue | CopySet | CopyBag | SetValue} V
+   * @param {B} brand
+   * @param {V} allegedValue
+   * @returns {B extends Brand<'nat'>
+   *     ? NatAmount
+   *     : V extends NatValue
+   *       ? NatAmount
+   *       : V extends CopySet
+   *         ? CopySetAmount<V['payload'][0]>
+   *         : V extends CopyBag
+   *           ? CopyBagAmount<V['payload'][0][0]>
+   *           : V extends SetValue
+   *             ? SetAmount<V[0]>
+   *             : never}
    */
-  // allegedValue has a conditional expression for type widening, to prevent V being bound to a a literal like 1n
   make: (brand, allegedValue) => {
     assertRemotable(brand, 'brand');
     const h = assertValueGetHelpers(allegedValue);
     const value = h.doCoerce(allegedValue);
+    // @ts-expect-error cast
     return harden({ brand, value });
   },
   /**
    * Make sure this amount is valid enough, and return a corresponding valid
    * amount if so.
    *
-   * @template {AssetKind} K
-   * @param {Brand<K>} brand
-   * @param {Amount<K>} allegedAmount
-   * @returns {Amount<K>}
+   * @template {Amount} A
+   * @param {Brand} brand
+   * @param {A} allegedAmount
+   * @returns {A}
    */
   coerce: (brand, allegedAmount) => {
     assertRemotable(brand, 'brand');
@@ -229,15 +240,16 @@ const AmountMath = {
     brand === allegedBrand ||
       Fail`The brand in the allegedAmount ${allegedAmount} in 'coerce' didn't match the specified brand ${brand}.`;
     // Will throw on inappropriate value
+    // @ts-expect-error cast
     return AmountMath.make(brand, allegedValue);
   },
   /**
    * Extract and return the value.
    *
-   * @template {AssetKind} K
-   * @param {Brand<K>} brand
-   * @param {Amount<K>} amount
-   * @returns {AssetValueForKind<K>}
+   * @template {Amount} A
+   * @param {Brand} brand
+   * @param {A} amount
+   * @returns {A['value']}
    */
   getValue: (brand, amount) => AmountMath.coerce(brand, amount).value,
   /**
@@ -246,29 +258,29 @@ const AmountMath = {
    *
    * @type {{
    *   (brand: Brand): Amount<'nat'>;
-   *   <K extends AssetKind>(brand: Brand, assetKind: K): Amount<K>;
+   *   <K extends AssetKind>(brand: Brand<K>, assetKind: K): Amount<K>;
    * }}
    */
   makeEmpty: (brand, assetKind = /** @type {const} */ ('nat')) => {
     assertRemotable(brand, 'brand');
     assertAssetKind(assetKind);
     const value = helpers[assetKind].doMakeEmpty();
+    // @ts-expect-error XXX narrowing from function overload
     return harden({ brand, value });
   },
   /**
    * Return the amount representing an empty amount, using another amount as the
    * template for the brand and assetKind.
    *
-   * @template {AssetKind} K
-   * @param {Amount<K>} amount
-   * @returns {Amount<K>}
+   * @template {Amount} A
+   * @param {A} amount
+   * @returns {A}
    */
   makeEmptyFromAmount: amount => {
     assertRecord(amount, 'amount');
     const { brand, value } = amount;
-    // @ts-expect-error cast
     const assetKind = assertValueGetAssetKind(value);
-    // @ts-expect-error cast (ignore b/c erroring in CI but not my IDE)
+    // @ts-expect-error different subtype
     return AmountMath.makeEmpty(brand, assetKind);
   },
   /**
@@ -291,10 +303,10 @@ const AmountMath = {
    * Returns true if the leftAmount equals the rightAmount. We assume that if
    * isGTE is true in both directions, isEqual is also true
    *
-   * @template {AssetKind} K
-   * @param {Amount<K>} leftAmount
-   * @param {Amount<K>} rightAmount
-   * @param {Brand<K>} [brand]
+   * @template {Amount} A
+   * @param {A} leftAmount
+   * @param {A} rightAmount
+   * @param {Brand} [brand]
    * @returns {boolean}
    */
   isEqual: (leftAmount, rightAmount, brand = undefined) => {
@@ -308,15 +320,16 @@ const AmountMath = {
    * amount, it usually means including all of the elements from both left and
    * right.
    *
-   * @template {AssetKind} K
-   * @param {Amount<K>} leftAmount
-   * @param {Amount<K>} rightAmount
-   * @param {Brand<K>} [brand]
-   * @returns {Amount<K>}
+   * @template {Amount} A
+   * @param {A} leftAmount
+   * @param {A} rightAmount
+   * @param {Brand} [brand]
+   * @returns {A}
    */
   add: (leftAmount, rightAmount, brand = undefined) => {
     const h = checkLRAndGetHelpers(leftAmount, rightAmount, brand);
     const value = h.doAdd(...coerceLR(h, leftAmount, rightAmount));
+    // @ts-expect-error different subtype
     return harden({ brand: leftAmount.brand, value });
   },
   /**
@@ -326,25 +339,27 @@ const AmountMath = {
    * error. Because the left amount must include the right amount, this is NOT
    * equivalent to set subtraction.
    *
-   * @template {AssetKind} K
-   * @param {Amount<K>} leftAmount
-   * @param {Amount<K>} rightAmount
-   * @param {Brand<K>} [brand]
-   * @returns {Amount<K>}
+   * @template {Amount} L
+   * @template {Amount} R
+   * @param {L} leftAmount
+   * @param {R} rightAmount
+   * @param {Brand} [brand]
+   * @returns {L extends R ? L : never}
    */
   subtract: (leftAmount, rightAmount, brand = undefined) => {
     const h = checkLRAndGetHelpers(leftAmount, rightAmount, brand);
     const value = h.doSubtract(...coerceLR(h, leftAmount, rightAmount));
+    // @ts-expect-error different subtype
     return harden({ brand: leftAmount.brand, value });
   },
   /**
    * Returns the min value between x and y using isGTE
    *
-   * @template {AssetKind} K
-   * @param {Amount<K>} x
-   * @param {Amount<K>} y
-   * @param {Brand<K>} [brand]
-   * @returns {Amount<K>}
+   * @template {Amount} A
+   * @param {A} x
+   * @param {A} y
+   * @param {Brand} [brand]
+   * @returns {A}
    */
   min: (x, y, brand = undefined) =>
     // eslint-disable-next-line no-nested-ternary
@@ -356,11 +371,11 @@ const AmountMath = {
   /**
    * Returns the max value between x and y using isGTE
    *
-   * @template {AssetKind} K
-   * @param {Amount<K>} x
-   * @param {Amount<K>} y
-   * @param {Brand<K>} [brand]
-   * @returns {Amount<K>}
+   * @template {Amount} A
+   * @param {A} x
+   * @param {A} y
+   * @param {Brand} [brand]
+   * @returns {A}
    */
   max: (x, y, brand = undefined) =>
     // eslint-disable-next-line no-nested-ternary
@@ -376,7 +391,6 @@ harden(AmountMath);
 const getAssetKind = amount => {
   assertRecord(amount, 'amount');
   const { value } = amount;
-  // @ts-expect-error cast (ignore b/c erroring in CI but not my IDE)
   return assertValueGetAssetKind(value);
 };
 harden(getAssetKind);

packages/ERTP/src/issuerKit.js

@@ -325,7 +325,7 @@ harden(prepareIssuerKit);
  *   anything else is corrupted by that corrupted state. See
  *   https://github.com/Agoric/agoric-sdk/issues/3434
  * @param {IssuerOptionsRecord} [options]
- * @returns {IssuerKit<K>}
+ * @returns {IssuerKit<K, any>}
  */
 export const makeIssuerKit = (
   name,

packages/ERTP/src/legacy-payment-helpers.js

@@ -26,18 +26,19 @@ const { Fail } = assert;
  */
 
 /**
- * @template {AssetKind} K
- * @param {ERef<Purse<K>>} recoveryPurse
- * @param {ERef<Payment<K>>} srcPaymentP
+ * @template {Payment} P
+ * @param {ERef<Purse>} recoveryPurse
+ * @param {ERef<P>} srcPaymentP
  * @param {Pattern} [optAmountShape]
- * @returns {Promise<Payment<K>>}
+ * @returns {Promise<P>}
  */
 export const claim = async (
   recoveryPurse,
   srcPaymentP,
   optAmountShape = undefined,
 ) => {
   const srcPayment = await srcPaymentP;
+  // @ts-expect-error XXX could be instantiated with a different subtype
   return E.when(E(recoveryPurse).deposit(srcPayment, optAmountShape), amount =>
     E(recoveryPurse).withdraw(amount),
   );