feat(ertp,zoe): minimal want patterns using M.has(el,n)

Author: erights

packages/ERTP/package.json

@@ -48,6 +48,7 @@
     "@endo/far": "^1.1.10",
     "@endo/marshal": "^1.6.3",
     "@endo/nat": "^5.0.14",
+    "@endo/pass-style": "^1.4.8",
     "@endo/patterns": "^1.4.8",
     "@endo/promise-kit": "^1.1.9"
   },

packages/ERTP/src/amountMath.js

@@ -1,15 +1,16 @@
 import { q, Fail } from '@endo/errors';
-import { passStyleOf, assertRemotable, assertRecord } from '@endo/marshal';
+import { assertRemotable, assertRecord, assertChecker } from '@endo/pass-style';
+import { containerHasSplit, kindOf, mustMatch } from '@endo/patterns';
 
-import { M, matches } from '@agoric/store';
 import { natMathHelpers } from './mathHelpers/natMathHelpers.js';
 import { setMathHelpers } from './mathHelpers/setMathHelpers.js';
 import { copySetMathHelpers } from './mathHelpers/copySetMathHelpers.js';
 import { copyBagMathHelpers } from './mathHelpers/copyBagMathHelpers.js';
+import { AmountShape } from './typeGuards.js';
 
 /**
- * @import {CopyBag, CopySet} from '@endo/patterns';
- * @import {Amount, AmountValue, AssetValueForKind, Brand, CopyBagAmount, CopySetAmount, MathHelpers, NatAmount, NatValue, SetAmount, SetValue} from './types.js';
+ * @import {Key, CopyBag, CopySet} from '@endo/patterns';
+ * @import {Amount, AmountBound, AssetValueForKind, Brand, CopyBagAmount, CopySetAmount, MathHelpers, NatAmount, NatValue, SetAmount, SetValue, HasBound} from './types.js';
  */
 
 // NB: AssetKind is both a constant for enumerated values and a type for those values.
@@ -75,39 +76,42 @@ const helpers = {
   copyBag: copyBagMathHelpers,
 };
 
-/** @type {(value: unknown) => 'nat' | 'set' | 'copySet' | 'copyBag'} } */
-const assertValueGetAssetKind = value => {
-  const passStyle = passStyleOf(value);
-  if (passStyle === 'bigint') {
-    return 'nat';
-  }
-  if (passStyle === 'copyArray') {
-    return 'set';
-  }
-  if (matches(value, M.set())) {
-    return 'copySet';
-  }
-  if (matches(value, M.bag())) {
-    return 'copyBag';
+/**
+ * @template {AssetKind} K=AssetKind
+ * @template {Key} M=Key
+ * @template {AssetValueForKind<K, M>} V=AssetValueForKind<K, M>
+ * @param {V} value
+ * @returns {AssetKind}
+ */
+export const assertValueGetAssetKind = value => {
+  const kind = kindOf(value);
+  switch (kind) {
+    case 'bigint': {
+      return 'nat';
+    }
+    case 'copyArray': {
+      return 'set';
+    }
+    case 'copySet':
+    case 'copyBag': {
+      return kind;
+    }
+    default: {
+      throw Fail`value ${value} must be an AmountValue, not ${q(kind)}`;
+    }
   }
-  // TODO This isn't quite the right error message, in case valuePassStyle
-  // is 'tagged'. We would need to distinguish what kind of tagged
-  // object it is.
-  // Also, this kind of manual listing is a maintenance hazard we
-  // (TODO) will encounter when we extend the math helpers further.
-  throw Fail`value ${value} must be a bigint, copySet, copyBag, or an array, not ${q(
-    passStyle,
-  )}`;
 };
 
 /**
  * Asserts that value is a valid AmountMath and returns the appropriate helpers.
  *
  * Made available only for testing, but it is harmless for other uses.
  *
- * @template {AmountValue} V
+ * @template {AssetKind} K=AssetKind
+ * @template {Key} M=Key
+ * @template {AssetValueForKind<K, M>} V=AssetValueForKind<K, M>
  * @param {V} value
- * @returns {MathHelpers<V>}
+ * @returns {MathHelpers<K, M, V>}
  */
 export const assertValueGetHelpers = value =>
   // @ts-expect-error cast
@@ -127,35 +131,38 @@ const optionalBrandCheck = (allegedBrand, brand) => {
 };
 
 /**
- * @template {AssetKind} K
+ * @template {AssetKind} K=AssetKind
+ * @template {Key} M=Key
+ * @template {AssetValueForKind<K, M>} V=AssetValueForKind<K, M>
  * @param {Amount<K>} leftAmount
  * @param {Amount<K>} rightAmount
  * @param {Brand<K> | undefined} brand
- * @returns {MathHelpers<any>}
+ * @returns {MathHelpers<K, M, V>}
  */
 const checkLRAndGetHelpers = (leftAmount, rightAmount, brand = undefined) => {
-  assertRecord(leftAmount, 'leftAmount');
-  assertRecord(rightAmount, 'rightAmount');
-  const { value: leftValue, brand: leftBrand } = leftAmount;
-  const { value: rightValue, brand: rightBrand } = rightAmount;
-  assertRemotable(leftBrand, 'leftBrand');
-  assertRemotable(rightBrand, 'rightBrand');
+  mustMatch(leftAmount, AmountShape, 'left amount');
+  mustMatch(rightAmount, AmountShape, 'right amount');
+  const { brand: leftBrand, value: leftValue } = leftAmount;
+  const { brand: rightBrand, value: rightValue } = rightAmount;
   optionalBrandCheck(leftBrand, brand);
   optionalBrandCheck(rightBrand, brand);
   leftBrand === rightBrand ||
     Fail`Brands in left ${q(leftBrand)} and right ${q(
       rightBrand,
     )} should match but do not`;
-  const leftHelpers = assertValueGetHelpers(leftValue);
-  const rightHelpers = assertValueGetHelpers(rightValue);
-  leftHelpers === rightHelpers ||
-    Fail`The left ${leftAmount} and right amount ${rightAmount} had different assetKinds`;
-  return leftHelpers;
+  const leftKind = assertValueGetAssetKind(leftValue);
+  const rightKind = assertValueGetAssetKind(rightValue);
+  leftKind === rightKind ||
+    Fail`The left ${leftAmount} and right amounts ${rightAmount} had different assetKinds: ${q(leftKind)} vs ${q(rightKind)}`;
+  // @ts-expect-error cast
+  return helpers[leftKind];
 };
 
 /**
- * @template {AssetKind} K
- * @param {MathHelpers<AssetValueForKind<K>>} h
+ * @template {AssetKind} K=AssetKind
+ * @template {Key} M=Key
+ * @template {AssetValueForKind<K, M>} V=AssetValueForKind<K, M>
+ * @param {MathHelpers<K, M, V>} h
  * @param {Amount<K>} leftAmount
  * @param {Amount<K>} rightAmount
  * @returns {[K, K]}
@@ -166,20 +173,54 @@ const coerceLR = (h, leftAmount, rightAmount) => {
 };
 
 /**
- * Returns true if the leftAmount is greater than or equal to the rightAmount.
- * The notion of "greater than or equal to" depends on the kind of amount, as
- * defined by the MathHelpers. For example, whether rectangle A is greater than
- * rectangle B depends on whether rectangle A includes rectangle B as defined by
- * the logic in MathHelpers.
+ * Returns true if the leftAmount is greater than or equal to the
+ * rightAmountBound. The notion of "greater than or equal to" depends on the
+ * kind of amount, as defined by the MathHelpers. For example, whether rectangle
+ * A is greater than rectangle B depends on whether rectangle A includes
+ * rectangle B as defined by the logic in MathHelpers.
+ *
+ * For non-fungible or sem-fungible amounts, the right operand can also be an
+ * `AmountBound` which can a normal concrete `Amount` or a specialized pattern:
+ * A `RecordPattern` of a normal concrete `brand: Brand` and a `value:
+ * HasBound`, as made by `M.containerHas(elementPattern)` or
+ * `M.containerHas(elementPattern, bigint)`. This represents those elements of
+ * the value collection that match the elementPattern, if that number is exactly
+ * the same as the bigint argument. If the second argument of `M.containerHas`
+ * is omitted, it defaults to `1n`. IOW, the left operand is `>=` such a bound
+ * if the total number of elements in the left operand that match the element
+ * pattern is `>=` the bigint argument in the `M.containerHas` pattern.
  *
  * @template {AssetKind} K
  * @param {Amount<K>} leftAmount
- * @param {Amount<K>} rightAmount
+ * @param {AmountBound<K>} rightAmountBound
  * @param {Brand<K>} [brand]
  * @returns {boolean}
  */
-const isGTE = (leftAmount, rightAmount, brand = undefined) => {
+const isGTE = (leftAmount, rightAmountBound, brand = undefined) => {
+  const { brand: rightBrand, value: rightValueBound } = rightAmountBound;
+  if (kindOf(rightValueBound) === 'match:containerHas') {
+    mustMatch(leftAmount, AmountShape, 'left amount');
+    const { brand: leftBrand, value: leftValue } = leftAmount;
+    const {
+      payload: [elementPatt, bound],
+    } = /** @type {HasBound} */ (rightValueBound);
+    optionalBrandCheck(leftBrand, brand);
+    optionalBrandCheck(rightBrand, brand);
+    leftBrand === rightBrand ||
+      Fail`Brands in left ${q(leftBrand)} and right ${q(
+        rightBrand,
+      )} should match but do not`;
+    const leftKind = assertValueGetAssetKind(leftValue);
+    leftKind !== 'nat' ||
+      Fail`can only use M.containerHas on container assets, not nat: ${leftValue}`;
+    const h = helpers[leftKind];
+    // @ts-expect-error param type of doCoerce should not be never
+    const lv = h.doCoerce(leftValue);
+    return !!containerHasSplit(lv, elementPatt, bound);
+  }
+  const rightAmount = /** @type {Amount<K>} */ (rightAmountBound);
   const h = checkLRAndGetHelpers(leftAmount, rightAmount, brand);
+  // @ts-expect-error cast?
   return h.doIsGTE(...coerceLR(h, leftAmount, rightAmount));
 };
 
@@ -309,6 +350,7 @@ export const AmountMath = {
    */
   isEqual: (leftAmount, rightAmount, brand = undefined) => {
     const h = checkLRAndGetHelpers(leftAmount, rightAmount, brand);
+    // @ts-expect-error cast?
     return h.doIsEqual(...coerceLR(h, leftAmount, rightAmount));
   },
   /**
@@ -326,26 +368,64 @@ export const AmountMath = {
    */
   add: (leftAmount, rightAmount, brand = undefined) => {
     const h = checkLRAndGetHelpers(leftAmount, rightAmount, brand);
+    // @ts-expect-error cast?
     const value = h.doAdd(...coerceLR(h, leftAmount, rightAmount));
     // @ts-expect-error different subtype
     return harden({ brand: leftAmount.brand, value });
   },
   /**
-   * Returns a new amount that is the leftAmount minus the rightAmount (i.e.
-   * everything in the leftAmount that is not in the rightAmount). If leftAmount
-   * doesn't include rightAmount (subtraction results in a negative), throw an
-   * error. Because the left amount must include the right amount, this is NOT
-   * equivalent to set subtraction.
+   * Returns a new amount that is the leftAmount minus the rightAmountBound
+   * (i.e. everything in the leftAmount that is not in the rightAmountBound). If
+   * leftAmount doesn't include rightAmountBound (subtraction results in a
+   * negative), throw an error. Because the left amount must include the right
+   * amount bound, this is NOT equivalent to set subtraction.
    *
-   * @template {Amount} L
-   * @template {Amount} R
+   * @template {AssetKind} K
+   * @template {Amount<K>} L
+   * @template {AmountBound<K>} R
    * @param {L} leftAmount
-   * @param {R} rightAmount
+   * @param {R} rightAmountBound
    * @param {Brand} [brand]
-   * @returns {L extends R ? L : never}
+   * @returns {L}
    */
-  subtract: (leftAmount, rightAmount, brand = undefined) => {
+  subtract: (leftAmount, rightAmountBound, brand = undefined) => {
+    const { brand: rightBrand, value: rightValueBound } = rightAmountBound;
+    if (kindOf(rightValueBound) === 'match:containerHas') {
+      mustMatch(leftAmount, AmountShape, 'left amount');
+      const { brand: leftBrand, value: leftValue } = leftAmount;
+      const {
+        payload: [elementPatt, bound],
+      } = /** @type {HasBound} */ (rightValueBound);
+      optionalBrandCheck(leftBrand, brand);
+      optionalBrandCheck(rightBrand, brand);
+      leftBrand === rightBrand ||
+        Fail`Brands in left ${q(leftBrand)} and right ${q(
+          rightBrand,
+        )} should match but do not`;
+      const leftKind = assertValueGetAssetKind(leftValue);
+      leftKind !== 'nat' ||
+        Fail`can only use M.containerHas on container assets, not nat: ${leftValue}`;
+      const h = helpers[leftKind];
+      // @ts-expect-error param type of doCoerce should not be never
+      const lv = h.doCoerce(leftValue);
+      // Passing in `assertChecker` as the `check` argument should guarantee
+      // that `value` is not `undefined`. It would have thrown first.
+      const [_, value] = containerHasSplit(
+        lv,
+        elementPatt,
+        bound,
+        false,
+        true,
+        assertChecker,
+      );
+      // @ts-expect-error cast?
+      return harden({ brand: leftBrand, value });
+    }
+    // @ts-expect-error I don't know why TS complains here but not in
+    // the identical case in isGTE
+    const rightAmount = /** @type {Amount<K>} */ (rightAmountBound);
     const h = checkLRAndGetHelpers(leftAmount, rightAmount, brand);
+    // @ts-expect-error cast?
     const value = h.doSubtract(...coerceLR(h, leftAmount, rightAmount));
     // @ts-expect-error different subtype
     return harden({ brand: leftAmount.brand, value });

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

@@ -40,6 +40,8 @@ export const claim = async (
 ) => {
   const srcPayment = await srcPaymentP;
   return E.when(E(recoveryPurse).deposit(srcPayment, optAmountShape), amount =>
+    // @ts-expect-error Why doesn't TS know that an Amount is a kind
+    // of AmountBound?
     E(recoveryPurse).withdraw(amount),
   );
 };
@@ -87,6 +89,8 @@ export const combine = async (
   if (optTotalAmount !== undefined) {
     mustMatch(total, optTotalAmount, 'amount');
   }
+  // @ts-expect-error Why doesn't TS know that an Amount is a kind
+  // of AmountBound?
   return E(recoveryPurse).withdraw(total);
 };
 harden(combine);
@@ -111,7 +115,11 @@ export const split = async (recoveryPurse, srcPaymentP, paymentAmountA) => {
   const srcAmount = await E(recoveryPurse).deposit(srcPayment);
   const paymentAmountB = AmountMath.subtract(srcAmount, paymentAmountA);
   return Promise.all([
+    // @ts-expect-error Why doesn't TS know that an Amount is a kind
+    // of AmountBound?
     E(recoveryPurse).withdraw(paymentAmountA),
+    // @ts-expect-error Why doesn't TS know that an Amount is a kind
+    // of AmountBound?
     E(recoveryPurse).withdraw(paymentAmountB),
   ]);
 };
@@ -147,6 +155,12 @@ export const splitMany = async (recoveryPurse, srcPaymentP, amounts) => {
   AmountMath.isEqual(srcAmount, total) ||
     Fail`rights were not conserved: ${total} vs ${srcAmount}`;
 
-  return Promise.all(amounts.map(amount => E(recoveryPurse).withdraw(amount)));
+  return Promise.all(
+    amounts.map(amount =>
+      // @ts-expect-error Why doesn't TS know that an Amount is a kind
+      // of AmountBound?
+      E(recoveryPurse).withdraw(amount),
+    ),
+  );
 };
 harden(splitMany);

packages/ERTP/src/mathHelpers/copyBagMathHelpers.js

@@ -11,12 +11,15 @@ import {
   bagDisjointSubtract,
 } from '@agoric/store';
 
-/** @import {MathHelpers} from '../types.js' */
+/**
+ * @import {Key, CopyBag} from '@endo/patterns'
+ * @import {MathHelpers} from '../types.js'
+ */
 
-/** @type {import('@endo/patterns').CopyBag} */
+/** @type {CopyBag} */
 const empty = makeCopyBag([]);
 
-/** @type {MathHelpers<import('@endo/patterns').CopyBag>} */
+/** @type {MathHelpers<'copyBag', Key, CopyBag<Key>>} */
 export const copyBagMathHelpers = harden({
   doCoerce: bag => {
     mustMatch(bag, M.bag(), 'bag of amount');

packages/ERTP/src/mathHelpers/copySetMathHelpers.js

@@ -9,17 +9,17 @@ import {
   setIsSuperset,
   setDisjointUnion,
   setDisjointSubtract,
-} from '@agoric/store';
+} from '@endo/patterns';
 
 /**
+ * @import {Key, CopySet} from '@endo/patterns'
  * @import {MathHelpers} from '../types.js'
- * @import {CopySet} from '@endo/patterns'
  */
 
 /** @type {CopySet} */
 const empty = makeCopySet([]);
 
-/** @type {MathHelpers<CopySet>} */
+/** @type {MathHelpers<'copySet', Key, CopySet<Key>>} */
 export const copySetMathHelpers = harden({
   doCoerce: set => {
     mustMatch(set, M.set(), 'set of amount');

packages/ERTP/src/mathHelpers/natMathHelpers.js

@@ -3,7 +3,10 @@
 import { Fail } from '@endo/errors';
 import { Nat, isNat } from '@endo/nat';
 
-/** @import {MathHelpers, NatValue} from '../types.js' */
+/**
+ * @import {Key} from '@endo/patterns'
+ * @import {MathHelpers, NatValue} from '../types.js'
+ */
 
 const empty = 0n;
 
@@ -16,7 +19,7 @@ const empty = 0n;
  * smallest whole unit such that the `natMathHelpers` never deals with
  * fractional parts.
  *
- * @type {MathHelpers<NatValue>}
+ * @type {MathHelpers<'nat', Key, NatValue>}
  */
 export const natMathHelpers = harden({
   doCoerce: nat => {