validate allocation in getCurrentAllocation

[turadg]

What is the Problem Being Solved?

We had a bug where the record from getCurrentAllocation was missing a key that was expected. This is because the return type is Record<Keyword, Amount<any>: #7195 (review)

Description of the Design

Make getCurrentAllocation return an accurate type description:

• the key may not be present in the record
• the amount kind may not be as expected

I tried making it return an UnknownKeywordRecord,

/**
 * @typedef {Record<Keyword, Amount<any>>} AmountKeywordRecord
 *
 * The keys are keywords, and the values are amounts. For example:
 * { Asset: AmountMath.make(assetBrand, 5n), Price:
 * AmountMath.make(priceBrand, 9n) }
 *
 * NB: this type hides the fact that the key may be absent or the
 * the amount may be of a different kind.
 * @see {UnknownAmountKeywordRecord}
 */

/**
 * @typedef {Record<Keyword, Amount | undefined>} UnknownAmountKeywordRecord
 */

That causes errors in the many places the allocation structure is assumed. We could have runtime checks in all those places but I propose that we instead add an optional "shape" parameter to getCurrentAllocation. It can mustMatch before returning. The return type should be aware of this runtime check. Making that work will depend on being able to infer the shape's static type from its own structure: #6160

Security Considerations

Scaling Considerations

Test Plan

[erights]

I like the idea of adding an optional shape parameter that gets mustMatched if present. Nice!