feat(ymax-planner): Improve the "No feasible solution" error message for a graph with debug: true (#12641)

## Description
* teach `preflightValidateNetworkPlan` about new AssetPlaceRef syntax (DepositFromChainRef `+${ChainName}` and WithdrawToChainRef `-${ChainName}`) to avoid errors like _`Unsupported position key: "+Ethereum"`_
* unquote the message for better readability
* translate `e$nn` edge ids into `$src->$dest` labels
* consolidate pick_e$nn and via_e$nn variable assignments for the same edge
* sort edges by ascending id
* underscore-separate number literal digits into groups of 3 such that e.g. 10k uusdc looks like "10_000_000_000".

### Security Considerations
None known

### Scaling Considerations
The increased object and text manipulation is a negligible burden, and even so, only applies when the solver rejects a flow graph.

### Documentation Considerations
n/a

### Testing Considerations
Since these error messages are intended to be human-friendly, added test coverage for them.

### Upgrade Considerations
Safe for immediate deployment.

Author: mergify[bot]

packages/portfolio-contract/test/rebalance.test.ts

@@ -626,6 +626,67 @@ testWithAllModes(
   },
 );
 
+test('infeasibility error with debug=true', async t => {
+  // @ts-expect-error fake chain names
+  const network: NetworkSpec = harden({
+    debug: true,
+    environment: 'test',
+    chains: [
+      { name: 'FakeSupply', control: 'axelar' },
+      { name: 'FakeSink', control: 'axelar' },
+    ],
+    pools: [
+      { pool: 'Aave_FakeSupply', chain: 'FakeSupply', protocol: 'Aave' },
+      { pool: 'Aave_FakeSink', chain: 'FakeSink', protocol: 'Aave' },
+    ],
+    links: [
+      {
+        src: '@FakeSupply',
+        dest: '@FakeSink',
+        transfer: 'cctpV2',
+        variableFeeBps: 0,
+        timeSec: 30,
+        min: 100_000n,
+      },
+      {
+        src: '@FakeSink',
+        dest: '@FakeSupply',
+        transfer: 'cctpV2',
+        variableFeeBps: 0,
+        timeSec: 30,
+        min: 100_000n,
+      },
+    ],
+  });
+  const current = { '+FakeSupply': token(10_000_000_000n) }; // $10k
+  const target = {
+    Aave_FakeSupply: token(9_999_990_000n),
+    // delta is too small for link
+    Aave_FakeSink: token(10000n),
+  };
+  let thrown: Error | undefined;
+  await null;
+  try {
+    await planRebalanceFlow({
+      network,
+      // @ts-expect-error fake chain names
+      current,
+      // @ts-expect-error fake chain names
+      target,
+      brand: TOK_BRAND,
+      feeBrand: FEE_BRAND,
+      gasEstimator,
+    });
+  } catch (err) {
+    thrown = err as Error;
+  }
+  t.assert(thrown);
+  t.is(
+    thrown?.message,
+    'No feasible solution: nodes=5 edges=11 | supply: pos 0 must equal neg 10000000000000000 (diff -10000000000000000) | WARN: total supply does not balance to 0 | sources=0 sinks=2 | hubs: @FakeSink, @FakeSupply | inter-hub edges: @FakeSupply->@FakeSink, @FakeSink->@FakeSupply | { feasible: false, result: 0, bounded: true, e01: { arc: "@FakeSupply->Aave_FakeSupply", pick: 0.009_999_990, via: 9_999_990_000.000_002 }, e02: { arc: "Aave_FakeSink->@FakeSink", via: 9_999_990_000.000_002 }, e10: { arc: "@FakeSink->@FakeSupply", pick: 0.009_999_990, via: 9_999_990_000.000_002 } }',
+  );
+});
+
 test('solver differentiates cheapest vs. fastest', async t => {
   const network: NetworkSpec = {
     debug: true,

packages/portfolio-contract/tools/graph-diagnose.ts

@@ -6,7 +6,12 @@ import { Fail, q } from '@endo/errors';
 import type { NatAmount } from '@agoric/ertp/src/types.js';
 import { provideLazyMap, typedEntries } from '@agoric/internal/src/js-utils.js';
 import { tryNow } from '@agoric/internal/src/ses-utils.js';
-import { isInterChainAccountRef } from '@agoric/portfolio-api/src/type-guards.js';
+import {
+  isDepositFromChainRef,
+  isInstrumentId,
+  isInterChainAccountRef,
+  isWithdrawToChainRef,
+} from '@agoric/portfolio-api/src/type-guards.js';
 import type {
   AssetPlaceRef,
   InterChainAccountRef,
@@ -42,7 +47,7 @@ const bfs = <T>(start: T, adj: Map<T, T[]>): Set<T> => {
  * Heuristics only: checks supply balance and reachability of sinks from sources.
  *
  * Example output (when graph.debug is true):
- *   No feasible solution: nodes=7 edges=12 | supply: sum=0 pos=1500 neg=1500 (pos should equal neg; sum should be 0) | sources=2 sinks=2 | sources with no path to any sink (1): Aave_Arbitrum(800) | hubs present: @agoric, @noble, @Arbitrum | inter-hub edges: @agoric->@noble, @noble->@Arbitrum
+ * `No feasible solution: nodes=7 edges=12 | supply: sum=0 pos=1500 neg=1500 (pos should equal neg; sum should be 0) | sources=2 sinks=2 | sources with no path to any sink (1): Aave_Arbitrum(800) | hubs: @agoric, @noble, @Arbitrum | inter-hub edges: @agoric->@noble, @noble->@Arbitrum`
  *
  * How to enable:
  *   - Set `debug: true` on the NetworkSpec used to build the graph.
@@ -109,7 +114,7 @@ export const diagnoseInfeasible = (
       `sources with no path to any sink (${stranded.length}): ${sample}`,
     );
   }
-  lines.push(`hubs present: ${[...hubSet].sort().join(', ')}`);
+  lines.push(`hubs: ${[...hubSet].sort().join(', ')}`);
   lines.push(
     `inter-hub edges: ${hubEdges.length ? hubEdges.join(', ') : '(none)'}`,
   );
@@ -155,8 +160,16 @@ export const preflightValidateNetworkPlan = (
     const tgt = target[k]?.value ?? 0n;
     if (cur === tgt) continue;
 
-    const placeInfo = PoolPlaces[k as PoolKey];
-    placeInfo || declared.has(k) || Fail`Unsupported position key: ${q(k)}`;
+    if (isInstrumentId(k)) {
+      const placeInfo = PoolPlaces[k as PoolKey];
+      placeInfo || declared.has(k) || Fail`Unsupported position key: ${q(k)}`;
+    } else {
+      [
+        isInterChainAccountRef,
+        isDepositFromChainRef,
+        isWithdrawToChainRef,
+      ].some(p => p(k)) || Fail`Unsupported key: ${q(k)}`;
+    }
     const chain = tryNow(
       () => chainOf(k),
       () => undefined,

packages/portfolio-contract/tools/plan-solve.ts

@@ -45,7 +45,14 @@ const replaceOrInit = <K, V>(
   map.set(key, callback(old, key, exists));
 };
 
-// XXX These probably belong in @agoric/internal.
+// #region XXX These probably belong in @agoric/internal.
+const compareStrings = (a: string, b: string) => (a < b ? -1 : a > b ? 1 : 0);
+
+const alphabetizeRecord = <T extends Record<string, unknown>>(obj: T) =>
+  Object.fromEntries(
+    Object.entries(obj).sort(([k1], [k2]) => compareStrings(k1, k2)),
+  );
+
 /**
  * Return the minimum and maximum bigint value from non-empty arguments, similar
  * to `Math.min` and `Math.max` (which don't work with bigints).
@@ -59,12 +66,14 @@ const bigIntExtremes = (first: bigint, ...rest: bigint[]) => {
   }
   return { min, max };
 };
+
 /**
  * Return the maximum bigint value from non-empty arguments, similar to
  * `Math.max` (which doesn't work with bigints).
  */
 const bigIntMax = (first: bigint, ...rest: bigint[]): bigint =>
   bigIntExtremes(first, ...rest).max;
+// #endregion
 
 /** The count of minor units per major unit (e.g., uusdc per USDC) */
 const UNIT_SCALE = 1e6;
@@ -350,7 +359,7 @@ const refineModel = (
 
 /**
  * Represent a JSON-serializable object as a spacey single-line literal with
- * identifier-compatible property names unquoted.
+ * identifier-compatible property names unquoted and number digits grouped.
  */
 const prettyJsonable = (obj: unknown): string => {
   const jsonText = JSON.stringify(obj, null, 1);
@@ -360,8 +369,24 @@ const prettyJsonable = (obj: unknown): string => {
     strings.push(s);
     return '#';
   });
-  // Condense the [now guaranteed-insignificant] whitespace.
-  const singleLine = safe.replace(/\s+/g, ' ');
+  // Condense the [now guaranteed-insignificant] whitespace and insert
+  // underscores to separate digits into groups of 3.
+  const singleLine = safe
+    .replace(/\s+/g, ' ')
+    .replace(/([0-9]+)([.][0-9]+)?/g, (_x, w, f = '') => {
+      const wCount = w.length;
+      const wGroups = w.slice(wCount % 3).match(/[0-9]{3}/g) || [];
+      if (wCount % 3) wGroups.unshift(w.slice(0, wCount % 3));
+
+      const fGroups = f.match(/[0-9]{1,3}/g) || [];
+      const lastFGroup = fGroups.pop();
+      if (lastFGroup) {
+        fGroups.push(lastFGroup.padEnd(3, '0'));
+        fGroups[0] = `.${fGroups[0]}`;
+      }
+
+      return `${wGroups.join('_')}${fGroups.join('_')}`;
+    });
   // Restore the strings, stripping quotes from property names as possible.
   const pretty = singleLine.replaceAll('#', () => {
     const s = strings.shift() as string;
@@ -371,6 +396,48 @@ const prettyJsonable = (obj: unknown): string => {
   return pretty;
 };
 
+/**
+ * Translate opaque variable names associated with edges (e.g., "pick_e00" and
+ * "via_e99") into ordered human-readable records like
+ * `"e00": { arc: "@agoric->@Ethereum", pick: 0.01, via: 1_000_000 }`.
+ */
+const summarizeSolution = (
+  graph: FlowGraph,
+  solution?: LpSolution,
+): null | Record<string, unknown> => {
+  if (!solution) return null;
+
+  const { base, edges } = typedEntries(solution).reduce<{
+    base: Record<string, unknown>;
+    edges: Record<string, unknown>;
+  }>(
+    (groups, [key, value]) => {
+      const keyParts = key.match(/^(.*?)_(e[0-9]+)$/);
+      if (!keyParts) {
+        groups.base[key] = value;
+      } else {
+        const [, kind, edgeId] = keyParts;
+        const edgeData = groups.edges[edgeId] as any;
+        if (!edgeData) {
+          const edge = graph.edges.find(e => e.id === edgeId);
+          const label = edge ? `${edge.src}->${edge.dest}` : '<unknown>';
+          groups.edges[edgeId] = { arc: label, [kind]: value };
+        } else {
+          const prevLastKey = Object.keys(edgeData).pop() as string;
+          edgeData[kind] = value;
+          if (kind < prevLastKey) {
+            const { arc, ...rest } = edgeData;
+            groups.edges[edgeId] = { arc, ...alphabetizeRecord(rest) };
+          }
+        }
+      }
+      return groups;
+    },
+    { base: { __proto__: null }, edges: { __proto__: null } },
+  );
+  return { ...base, ...alphabetizeRecord(edges) };
+};
+
 const solveLPModel = (
   model: LpModel,
   graph: FlowGraph,
@@ -382,11 +449,11 @@ const solveLPModel = (
   // instead. If result is undefined or there are no variable values, it's truly infeasible.
   if (!(solution?.feasible || solution?.result)) {
     if (graph.debug) {
-      // Emit richer context only on demand to avoid noisy passing runs
+      // Emit richer context.
       let msg = formatInfeasibleDiagnostics(graph, model);
-      msg += ` | ${prettyJsonable(solution)}`;
+      msg += ` | ${prettyJsonable(summarizeSolution(graph, solution))}`;
       console.error('[solver] No feasible solution. Diagnostics:', msg);
-      failUnsolvable(X`No feasible solution: ${msg}`);
+      failUnsolvable(`No feasible solution: ${msg}`);
     }
     failUnsolvable(X`No feasible solution: ${solution}`);
   }