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,21 @@
 import { q, Fail } from '@endo/errors';
-import { passStyleOf, assertRemotable, assertRecord } from '@endo/marshal';
+import { assertRemotable, assertRecord } from '@endo/pass-style';
+import { isKey, 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 {
+  AmountBoundShape,
+  AmountShape,
+  AmountValueHasBoundShape,
+} from './typeGuards.js';
 
 /**
- * @import {CopyBag, CopySet} from '@endo/patterns';
- * @import {Amount, AssetValueForKind, Brand, CopyBagAmount, CopySetAmount, MathHelpers, NatAmount, NatValue, SetAmount, SetValue} from './types.js';
+ * @import {Passable} from '@endo/pass-style'
+ * @import {Key, CopyBag, CopySet} from '@endo/patterns';
+ * @import {Amount, AmountBound, AmountValue, AssetValueForKind, Brand, CopyBagAmount, CopySetAmount, MathHelpers, NatAmount, NatValue, SetAmount, SetValue} from './types.js';
  */
 
 // NB: AssetKind is both a constant for enumerated values and a type for those values.
@@ -75,39 +81,42 @@ const helpers = {
   copyBag: copyBagMathHelpers,
 };
 
-/** @type {(value: unknown) => 'nat' | 'set' | 'copySet' | 'copyBag'} } */
+/**
+ * @template {AssetKind} K=AssetKind
+ * @template {Key} M=Key
+ * @template {AssetValueForKind<K, M>} V=AssetValueForKind<K, M>
+ * @param {V} value
+ * @returns {AssetKind}
+ */
 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';
+  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 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
@@ -125,35 +134,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]}
@@ -164,21 +176,53 @@ 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:
+ * AmountValueHasBound`, as made by `M.has(elementPattern)` or
+ * `M.has(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.has` 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.has` 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 h = checkLRAndGetHelpers(leftAmount, rightAmount, brand);
-  return h.doIsGTE(...coerceLR(h, leftAmount, rightAmount));
+const isGTE = (leftAmount, rightAmountBound, brand = undefined) => {
+  if (isKey(rightAmountBound)) {
+    const rightAmount = /** @type {Amount<K>} */ (rightAmountBound);
+    const h = checkLRAndGetHelpers(leftAmount, rightAmount, brand);
+    // @ts-expect-error cast?
+    return h.doIsGTE(...coerceLR(h, leftAmount, rightAmount));
+  }
+  mustMatch(leftAmount, AmountShape, 'left amount');
+  mustMatch(rightAmountBound, AmountBoundShape, 'right amount bound');
+  const { brand: leftBrand, value: leftValue } = leftAmount;
+  const { brand: rightBrand, value: rightValueHasBound } = rightAmountBound;
+  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);
+  // If it were anything else, it would have been a Key and so taken care of
+  // in the first case above.
+  mustMatch(rightValueHasBound, AmountValueHasBoundShape, 'right value bound');
+  const h = helpers[leftKind];
+  // @ts-expect-error cast?
+  return h.doIsGTE(h.doCoerce(leftValue), rightValueHasBound);
 };
 
 /**
@@ -307,6 +351,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));
   },
   /**
@@ -324,29 +369,58 @@ 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) => {
-    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 });
+  subtract: (leftAmount, rightAmountBound, brand = undefined) => {
+    if (isKey(rightAmountBound)) {
+      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 });
+    }
+    mustMatch(leftAmount, AmountShape, 'left amount');
+    mustMatch(rightAmountBound, AmountBoundShape, 'right amount bound');
+    const { brand: leftBrand, value: leftValue } = leftAmount;
+    const { brand: rightBrand, value: rightValueHasBound } = rightAmountBound;
+    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);
+    // If it were anything else, it would have been a Key and so taken care of
+    // in the first case above.
+    mustMatch(
+      rightValueHasBound,
+      AmountValueHasBoundShape,
+      'right value bound',
+    );
+    const h = helpers[leftKind];
+    // @ts-expect-error cast?
+    const value = h.doSubtract(h.doCoerce(leftValue), rightValueHasBound);
+    // @ts-expect-error cast?
+    return harden({ brand: leftBrand, value });
   },
   /**
    * Returns the min value between x and y using isGTE

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

@@ -12,14 +12,14 @@ import {
 } from '@agoric/store';
 
 /**
+ * @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,10 @@ const empty = 0n;
  * smallest whole unit such that the `natMathHelpers` never deals with
  * fractional parts.
  *
- * @type {MathHelpers<NatValue>}
+ * For this 'nat' asset kind, the rightBound is always a bigint, since a a
+ * fungible number has no "elements" to match against an elementPattern.
+ *
+ * @type {MathHelpers<'nat', Key, NatValue>}
  */
 export const natMathHelpers = harden({
   doCoerce: nat => {
@@ -27,9 +33,11 @@ export const natMathHelpers = harden({
   },
   doMakeEmpty: () => empty,
   doIsEmpty: nat => nat === empty,
-  doIsGTE: (left, right) => left >= right,
+  doIsGTE: (left, rightBound) =>
+    left >= /** @type {bigint} */ (/** @type {unknown} */ (rightBound)),
   doIsEqual: (left, right) => left === right,
   // BigInts don't observably overflow
   doAdd: (left, right) => left + right,
-  doSubtract: (left, right) => Nat(left - right),
+  doSubtract: (left, rightBound) =>
+    Nat(left - /** @type {bigint} */ (/** @type {unknown} */ (rightBound))),
 });