1488 Endo Passable

packages/ERTP/package.json

@@ -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

@@ -5,7 +5,7 @@ import { E } from '@endo/far';
 import { AmountMath } from './amountMath.js';
 
 /**
- * @import {ERef} from '@endo/far');
+ * @import {ERef} from '@endo/far';
  * @import {Amount, AssetKind, AmountValue, AssetKindForValue, Payment, Brand, Purse} from './types.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),
   );

packages/ERTP/src/paymentLedger.js

@@ -15,6 +15,7 @@ import { BrandI, makeIssuerInterfaces } from './typeGuards.js';
 /**
  * @import {Amount, AssetKind, DisplayInfo, PaymentLedger, Payment, Brand, RecoverySetsOption, Purse, Issuer, Mint} from './types.js'
  * @import {ShutdownWithFailure} from '@agoric/swingset-vat'
+ * @import {Key} from '@endo/patterns';
  */
 
 const { details: X, quote: q, Fail } = assert;
@@ -93,11 +94,7 @@ export const preparePaymentLedger = (
   optShutdownWithFailure = undefined,
 ) => {
   /** @type {Brand<K>} */
-  // Should be
-  // at-ts-expect-error XXX callWhen
-  // but ran into the usual disagreement between local lint and CI
-
-  // @ts-expect-error
+  // @ts-expect-error XXX callWhen
   const brand = issuerZone.exo(`${name} brand`, BrandI, {
     isMyIssuer(allegedIssuer) {
       // BrandI delays calling this method until `allegedIssuer` is a Remotable
@@ -299,7 +296,7 @@ export const preparePaymentLedger = (
   };
 
   /** @type {() => Purse<K>} */
-  // @ts-expect-error type parameter confusion
+  // @ts-expect-error XXX amount kinds
   const makeEmptyPurse = preparePurseKind(
     issuerZone,
     name,
@@ -315,11 +312,7 @@ export const preparePaymentLedger = (
   );
 
   /** @type {Issuer<K>} */
-  // Should be
-  // at-ts-expect-error cast due to callWhen discrepancy
-  // but ran into the usual disagreement between local lint and CI
-
-  // @ts-expect-error
+  // @ts-expect-error XXX callWhen
   const issuer = issuerZone.exo(`${name} issuer`, IssuerI, {
     getBrand() {
       return brand;
@@ -374,11 +367,6 @@ export const preparePaymentLedger = (
    * `makeIssuerKit` drops it on the floor, it can still be recovered in an
    * emergency upgrade.
    */
-  // Should be
-  // at-ts-expect-error checked cast
-  // but ran into the usual disagreement between local lint and IDE lint.
-  // Don't know yet about lint under CI.
-
   const mintRecoveryPurse = /** @type {Purse<K>} */ (
     issuerZone.makeOnce('mintRecoveryPurse', () => makeEmptyPurse())
   );
@@ -389,10 +377,6 @@ export const preparePaymentLedger = (
       return issuer;
     },
     mintPayment(newAmount) {
-      // Should be
-      // at-ts-expect-error checked cast
-      // but ran into the usual disagreement between local lint and CI
-
       newAmount = coerce(newAmount);
       mustMatch(newAmount, amountShape, 'minted amount');
       // `rawPayment` is not associated with any recovery set, and

packages/ERTP/src/transientNotifier.js

@@ -6,7 +6,7 @@ import { makeNotifierKit } from '@agoric/notifier';
 
 /**
  * @import {Purse} from './types.js';
- * @import {LatestTopic, NotifierRecord} from '@agoric/notifier');
+ * @import {NotifierRecord} from '@agoric/notifier';
  */
 
 // Note: Virtual for high cardinality, but *not* durable, and so