refactor(marshal): compareRankRemotablesTied for rank-cover ops (#3265)

Refs: #2871
Refs: #2883
Refs: #3226

## Description

Splits the rank-comparison refactor out from #2871 so that the
codec-admission core of that PR can land in #3226 without depending on
this orthogonal change.

Introduces `compareRankRemotablesTied` (and its anti-rank twin), which
behaves like `compareRank` but treats all remotables as tied for the
same rank rather than short-circuiting on the first remotable
encountered. Makes this the default `compare` for the rank-cover
operations:

- `isRankSorted`, `assertRankSorted`, `sortByRank`, `getIndexCover`
(commit 1)
- `unionRankCovers`, `intersectRankCovers` (commit 2)

`compare` becomes optional and is moved to the trailing position on
each. `getIndexCover`'s argument order shifts from `(sorted, compare,
rankCover)` to `(sorted, rankCover, compare?)`; the only callers are
within the Endo monorepo and are updated. `unionRankCovers` and
`intersectRankCovers` likewise shift from `(compare, covers)` to
`(covers, compare?)`, and `@endo/patterns`'s `patternMatchers.js` (the
only caller) is updated. `compareRankRemotablesTied` and
`compareAntiRankRemotablesTied` are re-exported from `@endo/marshal`'s
`index.js`.

The first commit is salvaged from #2871 with original authorship
preserved (Mark S. Miller).

### Security Considerations

No change to trust boundaries, no new authorities. The comparator change
is internal to marshal's rank ordering; callers that pass an explicit
`compare` keep their existing behavior.

### Scaling Considerations

The tied comparator visits every remotable rather than short-circuiting
on the first, so rank-cover operations over inputs containing many
remotables do more work per call than the prior `compareRank` default.
This matches the intent of the operations (they want a stable cover, not
an early exit), and the prior behavior is still available by passing
`compareRank` explicitly.

### Documentation Considerations

The argument-order changes on `getIndexCover`, `unionRankCovers`, and
`intersectRankCovers` are caller-visible. No internal callers remain on
the old signatures. External callers, if any, would need to swap
argument order; this is captured in the changeset.

### Testing Considerations

`packages/marshal/test/rankOrder.test.js` is extended to:

- Exercise the new optional/default-arg behavior of all six rank-cover
operations.
- Resolve two pre-existing TODOs that asked for the `totally orders
ranks` and `is transitive` property tests to run against both
`compareRank` and `compareRankRemotablesTied`. Both are total preorders,
so both properties hold for both, and we now parameterize the tests to
exercise each.

### Compatibility Considerations

Argument-order shifts on three exported functions (`getIndexCover`,
`unionRankCovers`, `intersectRankCovers`) and one new default comparator
on six. Captured in a changeset. The `compareRankRemotablesTied` and
`compareAntiRankRemotablesTied` exports are additions; nothing is
removed.

### Upgrade Considerations

No live-system upgrade concerns. The changeset covers the package-level
migration for external consumers.

Author: kriskowal

.changeset/rank-order-remotables-tied.md

@@ -0,0 +1,32 @@
+---
+'@endo/marshal': minor
+'@endo/patterns': patch
+---
+
+Add `compareRankRemotablesTied` and `compareAntiRankRemotablesTied`,
+which behave like `compareRank` and `compareAntiRank` except that they
+treat all remotables as tied for the same rank instead of short-circuiting
+the comparison on encountering a remotable.  Make the `compare` parameter
+optional on `isRankSorted`, `assertRankSorted`, `sortByRank`,
+`getIndexCover`, `unionRankCovers`, and `intersectRankCovers`,
+defaulting to `compareRankRemotablesTied`.
+
+The following parameter orders change so the optional comparator lands
+at the end:
+
+- `getIndexCover(sorted, compare, rankCover)` →
+  `getIndexCover(sorted, rankCover, compare?)`
+- `unionRankCovers(compare, covers)` →
+  `unionRankCovers(covers, compare?)`
+- `intersectRankCovers(compare, covers)` →
+  `intersectRankCovers(covers, compare?)`
+
+These are breaking changes to helpers that have no known external
+callers within the Endo monorepo.  Within the monorepo, the only
+callers of `unionRankCovers` and `intersectRankCovers` are in
+`@endo/patterns`'s `patternMatchers.js`, which has been updated to
+match the new parameter order.
+
+Salvaged from https://github.com/endojs/endo/pull/2871 so that the
+codec-admission core of that PR (now in #3226) can land independently
+of this rank-comparison refactor.

packages/marshal/index.js

@@ -19,9 +19,11 @@ export {
   compareByCodePoints,
   assertRankSorted,
   compareRank,
+  compareRankRemotablesTied,
   isRankSorted,
   sortByRank,
   compareAntiRank,
+  compareAntiRankRemotablesTied,
   makeFullOrderComparatorKit,
   getPassStyleCover,
   intersectRankCovers,

packages/marshal/src/rankOrder.js

@@ -359,12 +359,28 @@ harden(comparatorMirrorImage);
 export const { comparator: compareRank, antiComparator: compareAntiRank } =
   makeComparatorKit();
 
+/**
+ * Like `compareRank` and `compareAntiRank` and unlike `fullCompare`,
+ * `compareRankRemotablesTied` and `compareAntiRankRemotablesTied`
+ * considers all remotables tied for the same rank.
+ * Unlike `compareRank` and `compareAntiRank`,
+ * `compareRankRemotablesTied` and `compareAntiRankRemotablesTied`
+ * do not short circuit on encounting remotables.
+ */
+export const {
+  comparator: compareRankRemotablesTied,
+  antiComparator: compareAntiRankRemotablesTied,
+} = makeComparatorKit((_x, _y) => 0);
+
 /**
  * @param {Passable[]} passables
- * @param {RankCompare} compare
+ * @param {RankCompare} [compare]
  * @returns {boolean}
  */
-export const isRankSorted = (passables, compare) => {
+export const isRankSorted = (
+  passables,
+  compare = compareRankRemotablesTied,
+) => {
   const subMemoOfSorted = memoOfSorted.get(compare);
   assert(subMemoOfSorted !== undefined);
   if (subMemoOfSorted.has(passables)) {
@@ -383,9 +399,9 @@ harden(isRankSorted);
 
 /**
  * @param {Passable[]} sorted
- * @param {RankCompare} compare
+ * @param {RankCompare} [compare]
  */
-export const assertRankSorted = (sorted, compare) =>
+export const assertRankSorted = (sorted, compare = compareRankRemotablesTied) =>
   isRankSorted(sorted, compare) ||
   // TODO assert on bug could lead to infinite recursion. Fix.
   // eslint-disable-next-line no-use-before-define
@@ -395,10 +411,10 @@ harden(assertRankSorted);
 /**
  * @template {Passable} T
  * @param {Iterable<T>} passables
- * @param {RankCompare} compare
+ * @param {RankCompare} [compare]
  * @returns {T[]}
  */
-export const sortByRank = (passables, compare) => {
+export const sortByRank = (passables, compare = compareRankRemotablesTied) => {
   /** @type {T[]} mutable for in-place sorting, but with hardened elements */
   let unsorted;
   if (Array.isArray(passables)) {
@@ -439,12 +455,17 @@ harden(sortByRank);
  * https://en.wikipedia.org/wiki/Binary_search_algorithm#Procedure_for_finding_the_leftmost_element
  *
  * @param {Passable[]} sorted
- * @param {RankCompare} compare
  * @param {Passable} key
- * @param {("leftMost" | "rightMost")=} bias
+ * @param {RankCompare} [compare]
+ * @param {"leftMost" | "rightMost"} [bias]
  * @returns {number}
  */
-const rankSearch = (sorted, compare, key, bias = 'leftMost') => {
+const rankSearch = (
+  sorted,
+  key,
+  compare = compareRankRemotablesTied,
+  bias = 'leftMost',
+) => {
   assertRankSorted(sorted, compare);
   let left = 0;
   let right = sorted.length;
@@ -463,14 +484,19 @@ const rankSearch = (sorted, compare, key, bias = 'leftMost') => {
 
 /**
  * @param {Passable[]} sorted
- * @param {RankCompare} compare
  * @param {RankCover} rankCover
+ * @param {RankCompare} [compare] which rank comparison function to use.
+ * Default to `compareRankRemotablesTied`.
  * @returns {IndexCover}
  */
-export const getIndexCover = (sorted, compare, [leftKey, rightKey]) => {
+export const getIndexCover = (
+  sorted,
+  [leftKey, rightKey],
+  compare = compareRankRemotablesTied,
+) => {
   assertRankSorted(sorted, compare);
-  const leftIndex = rankSearch(sorted, compare, leftKey, 'leftMost');
-  const rightIndex = rankSearch(sorted, compare, rightKey, 'rightMost');
+  const leftIndex = rankSearch(sorted, leftKey, compare, 'leftMost');
+  const rightIndex = rankSearch(sorted, rightKey, compare, 'rightMost');
   return [leftIndex, rightIndex];
 };
 harden(getIndexCover);
@@ -524,11 +550,15 @@ const maxRank = (compare, a, b) => (compare(a, b) >= 0 ? a : b);
 const minRank = (compare, a, b) => (compare(a, b) <= 0 ? a : b);
 
 /**
- * @param {RankCompare} compare
  * @param {RankCover[]} covers
+ * @param {RankCompare} [compare] which rank comparison function to use.
+ * Default to `compareRankRemotablesTied`.
  * @returns {RankCover}
  */
-export const unionRankCovers = (compare, covers) => {
+export const unionRankCovers = (
+  covers,
+  compare = compareRankRemotablesTied,
+) => {
   /**
    * @param {RankCover} a
    * @param {RankCover} b
@@ -543,11 +573,15 @@ export const unionRankCovers = (compare, covers) => {
 harden(unionRankCovers);
 
 /**
- * @param {RankCompare} compare
  * @param {RankCover[]} covers
+ * @param {RankCompare} [compare] which rank comparison function to use.
+ * Default to `compareRankRemotablesTied`.
  * @returns {RankCover}
  */
-export const intersectRankCovers = (compare, covers) => {
+export const intersectRankCovers = (
+  covers,
+  compare = compareRankRemotablesTied,
+) => {
   /**
    * @param {RankCover} a
    * @param {RankCover} b