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';
+  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)}`;
+    }
   }
-  if (matches(value, M.bag())) {
-    return 'copyBag';
-  }
-  // 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,42 @@ 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.
  *
  * @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 +340,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,6 +358,7 @@ 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 });
@@ -344,6 +379,7 @@ export const AmountMath = {
    */
   subtract: (leftAmount, rightAmount, brand = undefined) => {
     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/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,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 => {

packages/ERTP/src/mathHelpers/setMathHelpers.js

@@ -10,7 +10,10 @@ import {
   elementsCompare,
 } from '@agoric/store';
 
-/** @import {MathHelpers, SetValue} from '../types.js' */
+/**
+ * @import {Key} from '@endo/patterns'
+ * @import {MathHelpers, SetValue} from '../types.js'
+ */
 
 // Operations for arrays with unique objects identifying and providing
 // information about digital assets. Used for Zoe invites.
@@ -19,7 +22,7 @@ const empty = harden([]);
 
 /**
  * @deprecated Replace array-based SetMath with CopySet-based CopySetMath
- * @type {MathHelpers<SetValue>}
+ * @type {MathHelpers<'set', Key, SetValue<Key>>}
  */
 export const setMathHelpers = harden({
   doCoerce: list => {

packages/ERTP/src/typeGuards.js

@@ -2,7 +2,7 @@
 
 import { M, matches, getInterfaceGuardPayload } from '@endo/patterns';
 /**
- * @import {AmountValue, Ratio} from './types.js'
+ * @import {AmountValue, Amount, AmountValueHasBound, AmountValueBound, AmountBound, Ratio} from './types.js'
  * @import {TypedPattern} from '@agoric/internal'
  */
 
@@ -68,13 +68,18 @@ const SetValueShape = M.arrayOf(M.key());
  */
 const CopyBagValueShape = M.bag();
 
+/**
+ * @see {AmountValue}
+ * @see {AssetValueForKind}
+ */
 const AmountValueShape = M.or(
   NatValueShape,
   CopySetValueShape,
   SetValueShape,
   CopyBagValueShape,
 );
 
+/** @see {Amount} */
 export const AmountShape = { brand: BrandShape, value: AmountValueShape };
 harden(AmountShape);
 
@@ -91,6 +96,22 @@ harden(AmountShape);
  */
 export const AmountPatternShape = M.pattern();
 
+/** @see {AmountValueHasBound} */
+export const AmountValueHasBoundShape = M.tagged(
+  'match:has',
+  M.splitArray([M.pattern(), M.bigint()], [M.record()]),
+);
+
+/** @see {AmountValueBound} */
+const AmountValueBoundShape = M.or(AmountValueShape, AmountValueHasBoundShape);
+
+/** @see {AmountBound} */
+export const AmountBoundShape = {
+  brand: BrandShape,
+  value: AmountValueBoundShape,
+};
+harden(AmountBoundShape);
+
 /** @type {TypedPattern<Ratio>} */
 export const RatioShape = { numerator: AmountShape, denominator: AmountShape };
 harden(RatioShape);