fix: unify maxDrawdown sign convention

Author: Deevhyne1023

packages/strategies/src/report.ts

@@ -508,6 +508,8 @@ export function mergeReports(
   // continuation's volatility / sharpeProxy, since the continuation reflects
   // the most recent regime. Callers that need a mathematically combined
   // metric should recompute from raw timeseries; this merge is best-effort.
+  // `maxDrawdown` is a non-negative ratio (0 = no drawdown, 1 = total loss),
+  // so the larger value is the more severe drawdown.
   const maxDrawdown =
     base.riskMetrics.maxDrawdown.compareTo(
       continuation.riskMetrics.maxDrawdown

packages/strategies/src/risk-metrics.test.ts

@@ -153,10 +153,10 @@ describe("valueAtRisk", () => {
 });
 
 describe("maxDrawdown", () => {
-  it("returns the most negative entry", () => {
+  it("returns the largest decline as a non-negative fraction", () => {
     const worst = maxDrawdown(series("0", "-0.02", "-0.05", "-0.01"));
 
-    expect(worst.toString()).toBe("-0.050000000000000000");
+    expect(worst.toString()).toBe("0.050000000000000000");
   });
 
   it("returns zero for an empty series", () => {
@@ -171,7 +171,7 @@ describe("maxDrawdown", () => {
 
   it("returns the only entry of a single-element series", () => {
     expect(maxDrawdown(series("-0.03")).toString()).toBe(
-      "-0.030000000000000000"
+      "0.030000000000000000"
     );
   });
 });
@@ -186,7 +186,7 @@ describe("computeRiskMetrics", () => {
       confidenceLevel: 0.95,
     });
 
-    expect(metrics.maxDrawdown.toString()).toBe("-0.050000000000000000");
+    expect(metrics.maxDrawdown.toString()).toBe("0.050000000000000000");
     expect(metrics.sharpeRatio.toString()).toBe("-0.200000000000000000");
     expect(metrics.valueAtRisk.toString()).toBe("0.050000000000000000");
   });

packages/strategies/src/risk-metrics.ts

@@ -16,16 +16,16 @@ import { Decimal } from "./decimal";
  * - `sharpeRatio` returns the per-period ratio. `annualizeSharpe` scales it by
  *   `sqrt(periodsPerYear)`, the convention for i.i.d. periods. Use 365 for a
  *   daily stablecoin-vault series, 52 weekly, 12 monthly.
- * - `maxDrawdown` is a signed decline, so it is 0 or lower. `valueAtRisk` is a
- *   loss magnitude, so a positive result is a loss. The two signs differ by
- *   intent and each is documented on its own function.
+ * - `maxDrawdown` is a non-negative magnitude, so it is 0 or higher.
+ *   `valueAtRisk` is also a loss magnitude, so a positive result is a loss.
+ *   Both are quoted as positive losses, matching the report field convention.
  */
 
 /** Scale used for ratio arithmetic. Stroops are too coarse for a variance. */
 const METRICS_SCALE = 18;
 
 export interface RiskMetrics {
-  /** Most negative entry of the drawdown series, 0 or lower. */
+  /** Most negative entry of the drawdown series as a magnitude, 0 or higher. */
   readonly maxDrawdown: Decimal;
   /** Per-period Sharpe ratio. Annualize with `annualizeSharpe`. */
   readonly sharpeRatio: Decimal;
@@ -134,8 +134,9 @@ export function valueAtRisk(
 
 /**
  * Most negative entry of the drawdown series, where each entry is the running
- * `value / peak - 1` decline. An empty series, and a series that never leaves
- * its running peak, both give `0`.
+ * `value / peak - 1` decline. The result is reported as a non-negative
+ * magnitude: the sign of the worst decline is flipped, so a series that never
+ * leaves its running peak gives `0`. An empty series also gives `0`.
  */
 export function maxDrawdown(drawdown: readonly Decimal[]): Decimal {
   const scale = workingScale(drawdown);
@@ -145,7 +146,7 @@ export function maxDrawdown(drawdown: readonly Decimal[]): Decimal {
       worst = value.rescale(scale);
     }
   }
-  return worst;
+  return worst.neg();
 }
 
 /** Computes all three metrics from the collector's series in one call. */