gloomberb 0.18.3 → 0.18.5

package/src/plugins/builtin/analytics/risk-model.ts

@@ -20,11 +20,23 @@ import {
   concentration,
   pairedReturns,
   regressReturns,
+  RISK_TAIL_CONFIDENCE,
+  RISK_TAIL_MINIMUM,
   rollingBasketRisk,
   rollingBeta,
   sinceBasketRisk,
   subtractReturns,
 } from "./risk-math";
+import {
+  repriceBook,
+  RISK_SHOCK_LIMITS,
+  riskCashLines,
+  type RiskAssetShift,
+  type RiskBookLine,
+  type RiskCashLine,
+  type RiskFxShift,
+  type RiskRepricing,
+} from "./risk-book";
 import {
   calculateAccountPerformance,
   calculateBrinson,
@@ -69,32 +81,51 @@ interface PortfolioRiskHolding {
   /** Why the holding is outside the basket; null when it qualifies. */
   leftOut: string | null;
 }
-/** A holding outside the basket, with its share of market value when one is known. */
+/** A holding or a currency's cash outside the basket, with its share of the book when one is known. */
 interface RiskLeftOut {
   id: string;
   symbol: string;
   reason: string;
   value: number | null;
   share: number | null;
+  /** Set on a currency's cash, which is never in the basket and does not make a report incomplete. */
+  cash?: true;
+}
+/** One currency of the book's cash, valued in the account currency. */
+interface RiskCashHolding extends RiskCashLine {
+  id: string;
+  /** "TRY cash". */
+  symbol: string;
+  /** Signed, in the portfolio currency at the current rate; null without a rate. */
+  value: number | null;
 }
 /** What the basket views cover of the account. */
 export interface RiskCoverage {
   currency: string;
-  /** Gross current value of every holding that has one, in the portfolio currency. */
+  /**
+   * Gross current value of the book in the portfolio currency: every holding
+   * that has one, and the cash.
+   */
   marketValue: number;
   coveredValue: number;
-  /** Covered share of market value; an upper bound while `unvalued` holdings have no value. */
+  /** Covered share of the book, cash included; an upper bound while `unvalued` lines have no value. */
   share: number | null;
+  /** Gross value of the holdings alone, and the covered share of it, which `sufficient` reads. */
+  holdingsValue?: number;
+  holdingsShare?: number | null;
+  /** Gross value of the cash in the portfolio currency. */
+  cashValue?: number;
   holdings: number;
   /** Holdings that qualify for the basket. */
   covered: number;
   /** Covered holdings whose returns were converted to USD from their listing currency. */
   converted: number;
+  /** Holdings and cash lines nothing values. */
   unvalued: number;
   minimumShare: number;
-  /** The basket views estimate only when qualifying holdings reach the minimum share. */
+  /** The basket views estimate only when qualifying holdings reach the minimum share of the holdings, cash aside. */
   sufficient: boolean;
-  /** Largest first. */
+  /** Holdings and cash, largest first. */
   leftOut: RiskLeftOut[];
 }
 export interface RiskDisplayRow {
@@ -112,10 +143,16 @@ export interface RiskDisplayRow {
   interaction?: number;
   /** Holdings rows only: why the holding is outside the covered basket. */
   leftOut?: string;
-  /** VaR and expected shortfall only: the loss `value` is on the covered basket's current value (`amountBase`), in `amountCurrency`. */
+  /**
+   * A loss or change in money beside `value`, in `amountCurrency`: VaR and
+   * expected shortfall on the covered basket's current value (`amountBase`),
+   * a shock on the repriced line.
+   */
   amount?: number;
   amountCurrency?: string;
   amountBase?: number;
+  /** What a tail loss in money is taken on: the basket's value and share of the book, and what it leaves out. */
+  basis?: string;
 }
 /** The tail-loss rows, which also read in money on the covered basket. */
 const TAIL_ROW_IDS: ReadonlySet<string> = new Set(["var", "es"]);
@@ -144,6 +181,9 @@ export interface RiskShifts {
   equity: number;
   rates: number;
   volatility: number;
+  /** Currencies' moves against USD and holdings' own price moves, applied together to every line of the book. */
+  fx?: RiskFxShift[];
+  assets?: RiskAssetShift[];
 }
 /** The benchmark the basket's returns, active return and tracking error are measured against. */
 const RISK_BENCHMARK = "SPY";
@@ -330,6 +370,22 @@ function outsideValue(
   const value = resolvePortfolioMarketValue(metrics, unit != null && Number.isFinite(unit) ? unit : null)?.gross;
   return value != null && Number.isFinite(value) ? value : null;
 }
+/** Cash in the portfolio currency at the load's rates (USD per unit); null without a rate. */
+function cashValue(line: RiskCashLine, accountCurrency: string, rates: Readonly<Record<string, number>>): number | null {
+  const unit = resolveCurrencyUnit(line.currency);
+  if (unit.currency === accountCurrency) return line.amount / unit.divisor;
+  const usd = unit.currency === "USD" ? 1 : rates[unit.currency];
+  const account = accountCurrency === "USD" ? 1 : rates[accountCurrency];
+  const value = usd != null && usd > 0 && account != null && account > 0 ? (line.amount / unit.divisor) * usd / account : Number.NaN;
+  return Number.isFinite(value) ? value : null;
+}
+/** Why a currency's cash is outside the basket, and for one in another currency, what moves its value. */
+function cashReason(line: RiskCashLine, accountCurrency: string): string {
+  const own = resolveCurrencyUnit(line.currency).currency;
+  return own === accountCurrency
+    ? "Cash is outside the equity basket"
+    : `Cash is outside the equity basket; its ${accountCurrency} value moves with ${own}`;
+}
 /** USD returns in the account currency, or none with the reason its daily closes cannot convert them. */
 function accountReturns(returns: readonly DatedReturn[], account: AccountFx): { returns: DatedReturn[]; error: string | null } {
   if (account.error) return { returns: [], error: account.error };
@@ -355,67 +411,84 @@ const shareText = (share: number) =>
   share < 0.001 ? "under 0.1%" : `${(share * 100).toFixed(1)}%`;
 const convertedText = (coverage: RiskCoverage) =>
   coverage.converted ? `${holdingCount(coverage.converted)} converted from local currency` : null;
+/** Whole percents of shares that add up to one, the remainders handed out largest first, so a line of them adds up to 100. */
+function wholePercents(shares: readonly number[]): number[] {
+  const raw = shares.map((share) => share * 100);
+  const whole = raw.map((value) => Math.floor(value + 1e-9));
+  let left = Math.round(raw.reduce((sum, value) => sum + value, 0)) - whole.reduce((sum, value) => sum + value, 0);
+  const order = raw.map((_, index) => index).sort((a, b) => raw[b]! - whole[b]! - (raw[a]! - whole[a]!));
+  for (const index of order) {
+    if (left <= 0) break;
+    whole[index]! += 1;
+    left -= 1;
+  }
+  return whole;
+}
+const percentText = (percent: number, share: number) => (percent > 0 ? `${percent}%` : share > 0 ? "under 1%" : "0%");
+/** Lines the coverage line names before "N more". */
+const NAMED_EXCLUSIONS = 2;
 /**
- * "covers 78% of market value · 9 holdings left out · 2 converted from local
- * currency", or null when every holding is in the basket in its own USD listing.
- * The compact result for Ask Gloom reads this form; the report and the pane
- * name what is left out with `riskCoverageHeadline`.
+ * "basket 48,286 USD = 72% of book; left out: BTC-USD 10%, TRY cash 18%": the
+ * value the basket views estimate on, its share of the whole book (every
+ * holding and the cash), and what it leaves out, largest first, the percents
+ * adding up to 100. Past three lines left out the rest read "7 more 14%". The
+ * basket's share reads "at most" while a line has no value, and a line nothing
+ * values is named with "value unknown". Converted listings are counted after.
  */
-export function riskCoverageText(coverage: RiskCoverage | undefined): string | null {
+export function riskCoverageLine(coverage: RiskCoverage | undefined): string | null {
   if (!coverage) return null;
-  const converted = convertedText(coverage);
-  if (!coverage.leftOut.length) return converted;
-  const covers = coverage.share == null
-    ? "covers an unknown share of market value"
-    : `covers ${coverage.unvalued ? "at most " : ""}${coveragePercent(coverage.share)}% of market value`;
-  return [covers, `${holdingCount(coverage.leftOut.length)} left out`, ...(converted ? [converted] : [])].join(" · ");
+  const named = coverage.leftOut.length <= NAMED_EXCLUSIONS + 1 ? coverage.leftOut : coverage.leftOut.slice(0, NAMED_EXCLUSIONS);
+  const rest = coverage.leftOut.slice(named.length);
+  const restShare = rest.reduce((sum, row) => sum + (row.share ?? 0), 0);
+  const shares = [coverage.share ?? 0, ...named.map((row) => row.share ?? 0), ...(rest.length ? [restShare] : [])];
+  const percents = wholePercents(shares);
+  const basket = `basket ${formatNumber(coverage.coveredValue, 0)} ${coverage.currency}${coverage.share == null ? "" : ` = ${coverage.unvalued ? "at most " : ""}${percentText(percents[0]!, shares[0]!)} of book`}`;
+  const items = [
+    ...named.map((row, index) => `${row.symbol} ${row.share == null ? "value unknown" : percentText(percents[index + 1]!, row.share)}`),
+    ...(rest.length ? [`${rest.length} more${restShare > 0 ? ` ${percentText(percents.at(-1)!, restShare)}` : ""}`] : []),
+  ];
+  return [`${basket}${items.length ? `; left out: ${items.join(", ")}` : ""}`, convertedText(coverage)].filter(Boolean).join(" · ");
 }
-/** Holdings named before "+N more" in the exclusion text. */
-const NAMED_EXCLUSIONS = 2;
+/** Whether the basket leaves out a holding, which makes a report incomplete; cash never is in it. */
+export const riskHoldingsLeftOut = (coverage: RiskCoverage) => coverage.leftOut.some((row) => !row.cash);
 /**
- * What the basket leaves out, by name and combined share, from the same
- * covered share every other line reads: "excludes SQM, 12% of value" or
- * "excludes SQM, ALB +1 more, 41% of value". The share is the complement of the
- * covered percent, so the two always add to 100; it reads "at least" while a
- * holding has no value, and a holding nothing values is named with "value
- * unknown". Null when every holding is in the basket.
+ * "historical, 1-day, 95%, 60 daily returns": how VaR and expected shortfall
+ * are estimated, from the sample they read; without an estimate, how many
+ * returns it needs.
  */
-export function riskExclusionText(coverage: RiskCoverage | undefined): string | null {
-  if (!coverage?.leftOut.length) return null;
-  const named = coverage.leftOut.slice(0, NAMED_EXCLUSIONS).map((row) => row.symbol).join(", ");
-  const more = coverage.leftOut.length - NAMED_EXCLUSIONS;
-  const names = more > 0 ? `${named} +${more} more` : named;
-  if (coverage.share == null || !coverage.leftOut.some((row) => (row.share ?? 0) > 0))
-    return `excludes ${names}, value unknown`;
-  const percent = 100 - coveragePercent(coverage.share);
-  return `excludes ${names}, ${coverage.unvalued ? "at least " : ""}${percent > 0 ? `${percent}%` : "under 1%"} of value`;
-}
-/** The line that leads what the basket views cover: what is left out, then what converted from local currency. */
-export function riskCoverageHeadline(coverage: RiskCoverage | undefined): string | null {
-  if (!coverage) return null;
-  return [riskExclusionText(coverage), convertedText(coverage)].filter(Boolean).join(" · ") || null;
+function riskTailMethod(samples: number, estimated: boolean): string {
+  const head = `historical, 1-day, ${Math.round(RISK_TAIL_CONFIDENCE * 100)}%`;
+  return estimated
+    ? `${head}, ${samples} daily returns`
+    : `${head}; needs ${RISK_TAIL_MINIMUM} daily returns${samples ? `, has ${samples}` : ""}`;
 }
+/** The unit of the concentration shares, which divide the priced holdings' value, cash aside. */
+export const HOLDINGS_SHARE_UNIT = "% holdings";
 /** A reason reads as the tail of a sentence, so its first word loses its capital unless it is an acronym ("FX", "USD"). */
 const lowerFirst = (text: string) => (/^[A-Z][a-z]/.test(text) ? text[0]!.toLowerCase() + text.slice(1) : text);
-/** One sentence per left-out holding, largest first, naming the holding and why it is out. */
+/** One sentence per holding or cash left out, largest first, naming it and why it is out. */
 export function riskCoverageNotices(coverage: RiskCoverage | undefined): string[] {
   if (!coverage?.leftOut.length) return [];
   return coverage.leftOut.map(
     (row) =>
-      `${row.symbol} (${row.share == null ? "value unknown" : `${shareText(row.share)} of market value`}) is excluded from the risk estimate: ${lowerFirst(row.reason.replace(/\.$/, ""))}.`,
+      `${row.symbol} (${row.share == null ? "value unknown" : `${shareText(row.share)} of the book`}) is excluded from the risk estimate: ${lowerFirst(row.reason.replace(/\.$/, ""))}.`,
   );
 }
-/** Why the basket views show no estimate, when too little of the account qualifies. */
+/** Why the basket views show no estimate, when too little of the holdings qualifies. */
 export function riskCoverageShortfall(
   coverage: RiskCoverage | undefined,
 ): { title: string; message: string } | null {
   if (!coverage || coverage.sufficient) return null;
   if (!coverage.holdings) return { title: "No holdings in this portfolio.", message: "" };
   const minimum = Math.round(coverage.minimumShare * 100);
+  // A share of what is invested: cash is no holding the basket could take.
+  const share = coverage.holdingsShare !== undefined ? coverage.holdingsShare : coverage.share;
+  const base = coverage.holdingsValue ?? coverage.marketValue;
   const reasons = new Map<string, { share: number; count: number }>();
   for (const row of coverage.leftOut) {
+    if (row.cash) continue;
     const entry = reasons.get(row.reason) ?? { share: 0, count: 0 };
-    entry.share += row.share ?? 0;
+    entry.share += row.value != null && base > 0 ? row.value / base : 0;
     entry.count += 1;
     reasons.set(row.reason, entry);
   }
@@ -423,14 +496,51 @@ export function riskCoverageShortfall(
     ([, left], [, right]) => right.share - left.share || right.count - left.count,
   )[0] ?? [];
   return {
-    title: coverage.covered === 0 || coverage.share == null
-      ? `No holding qualifies for basket estimates, which need ${minimum}% of market value.`
-      : `Qualifying holdings cover ${coverage.unvalued ? "at most " : ""}${coveragePercent(coverage.share)}% of market value; basket estimates need ${minimum}%.`,
+    title: coverage.covered === 0 || share == null
+      ? `No holding qualifies for basket estimates, which need ${minimum}% of the holdings' value.`
+      : `Qualifying holdings cover ${coverage.unvalued ? "at most " : ""}${coveragePercent(share)}% of the holdings' value; basket estimates need ${minimum}%.`,
     message: reason
-      ? `Most of what is left out: ${reason}${largest!.share > 0 ? ` (${shareText(largest!.share)} of market value)` : ""}.`
+      ? `Most of what is left out: ${reason}${largest!.share > 0 ? ` (${shareText(largest!.share)} of the holdings' value)` : ""}.`
       : "",
   };
 }
+/**
+ * The stress rows of the given shocks: each line they move, its change in
+ * percent of its own value and in money, then the book's total, in percent of
+ * its net value with the cash.
+ */
+/** The Stress row that totals the currency and price shocks over the whole book. */
+export const BOOK_TOTAL_ROW_ID = "shock:book";
+/** A Stress row of the currency and price shocks, which reprice the book without the basket. */
+export function isShockRow(row: Pick<RiskDisplayRow, "id">): boolean {
+  return row.id.startsWith("shock:");
+}
+function repricingRows(repricing: RiskRepricing, currency: string, asOf: string): RiskDisplayRow[] {
+  const money = (value: number) => `${formatNumber(value, 0)} ${currency}`;
+  return [
+    ...repricing.lines.map((line) => ({
+      id: `shock:${line.id}`,
+      label: line.label,
+      value: line.percent,
+      unit: "%",
+      percentile: null,
+      asOf,
+      detail: `${line.shocks.join(", ")}; ${line.before == null || line.after == null ? "value unknown, not repriced" : `${money(line.before)} to ${money(line.after)}`}`,
+      ...(line.change != null ? { amount: line.change, amountCurrency: currency } : {}),
+    })),
+    {
+      id: BOOK_TOTAL_ROW_ID,
+      label: "Book total",
+      value: repricing.percent,
+      unit: "%",
+      percentile: null,
+      asOf,
+      detail: `${repricing.scenario}; of ${money(repricing.bookValue)} book, cash included${repricing.unvalued.length ? `; ${repricing.unvalued.join(", ")} without a value not repriced` : ""}`,
+      amount: repricing.change,
+      amountCurrency: currency,
+    },
+  ];
+}
 /**
  * Basket estimates use the holdings that qualify, reweighted among themselves.
  * Every other holding stays listed with its reason and counts in the market
@@ -443,6 +553,8 @@ export function buildPortfolioRisk(
   evidence: PortfolioRiskEvidence | null = null,
   shifts: RiskShifts = DEFAULT_RISK_SHIFTS,
   window: RiskWindowRequest = {},
+  /** The book's cash by currency; the portfolio's own entry when left out. */
+  cash: readonly RiskCashLine[] = riskCashLines(portfolio, null),
 ) {
   if (
     ![shifts.equity, shifts.rates, shifts.volatility].every(Number.isFinite) ||
@@ -450,7 +562,9 @@ export function buildPortfolioRisk(
     Math.abs(shifts.equity) > 100 ||
     Math.abs(shifts.rates) > 500 ||
     shifts.volatility < -50 ||
-    shifts.volatility > 100
+    shifts.volatility > 100 ||
+    [...(shifts.fx ?? []), ...(shifts.assets ?? [])].some((shift) =>
+      !Number.isFinite(shift.percent) || shift.percent < RISK_SHOCK_LIMITS.minimum || shift.percent > RISK_SHOCK_LIMITS.maximum)
   )
     throw new Error("Stress shifts exceed the supported range");
   if (
@@ -580,33 +694,59 @@ export function buildPortfolioRisk(
       leftOut,
     };
   });
+  // Each currency's cash once, valued in the portfolio currency.
+  const cashTotals = new Map<string, number>();
+  for (const line of cash)
+    if (Number.isFinite(line.amount) && line.amount !== 0)
+      cashTotals.set(line.currency, (cashTotals.get(line.currency) ?? 0) + line.amount);
+  const cashHoldings: RiskCashHolding[] = [...cashTotals].map(([currency, amount]) => ({
+    id: `cash:${currency}`,
+    symbol: `${currency} cash`,
+    currency,
+    amount,
+    value: cashValue({ currency, amount }, portfolio.currency, rates),
+  }));
   const qualifying = holdings.filter((row) => row.leftOut == null);
   const valued = holdings.filter((row) => row.marketValue != null);
-  const marketValue = valued.reduce((sum, row) => sum + row.marketValue!, 0);
+  const holdingsValue = valued.reduce((sum, row) => sum + row.marketValue!, 0);
+  // Cash counts in the book the coverage is a share of, at its gross value as a short does.
+  const cashGross = cashHoldings.reduce((sum, row) => sum + Math.abs(row.value ?? 0), 0);
+  const marketValue = holdingsValue + cashGross;
   const coveredValue = qualifying.reduce((sum, row) => sum + row.value!, 0);
   const share = marketValue > 0 ? coveredValue / marketValue : null;
-  const sufficient = qualifying.length > 0 && share != null && share >= RISK_MIN_COVERAGE;
+  // Whether the basket is most of what is invested: cash is no holding the basket could have taken.
+  const holdingsShare = holdingsValue > 0 ? coveredValue / holdingsValue : null;
+  const sufficient = qualifying.length > 0 && holdingsShare != null && holdingsShare >= RISK_MIN_COVERAGE;
+  const bookShare = (value: number | null) => value != null && marketValue > 0 ? value / marketValue : null;
   const coverage: RiskCoverage = {
     currency: portfolio.currency,
     marketValue,
     coveredValue,
     share,
+    holdingsValue,
+    holdingsShare,
+    cashValue: cashGross,
     holdings: holdings.length,
     covered: qualifying.length,
     converted: qualifying.filter((row) => row.convertedFrom != null).length,
-    unvalued: holdings.length - valued.length,
+    unvalued: holdings.length - valued.length + cashHoldings.filter((row) => row.value == null).length,
     minimumShare: RISK_MIN_COVERAGE,
     sufficient,
-    leftOut: holdings
-      .filter((row) => row.leftOut != null)
-      .sort((a, b) => (b.marketValue ?? -1) - (a.marketValue ?? -1))
-      .map((row) => ({
-        id: row.id,
-        symbol: row.symbol,
-        reason: row.leftOut!,
-        value: row.marketValue,
-        share: row.marketValue != null && marketValue > 0 ? row.marketValue / marketValue : null,
-      })),
+    leftOut: [
+      ...holdings
+        .filter((row) => row.leftOut != null)
+        .map((row): RiskLeftOut => ({
+          id: row.id,
+          symbol: row.symbol,
+          reason: row.leftOut!,
+          value: row.marketValue,
+          share: bookShare(row.marketValue),
+        })),
+      ...cashHoldings.map((row): RiskLeftOut => {
+        const value = row.value == null ? null : Math.abs(row.value);
+        return { id: row.id, symbol: row.symbol, reason: cashReason(row, portfolio.currency), value, share: bookShare(value), cash: true };
+      }),
+    ].sort((a, b) => (b.value ?? -1) - (a.value ?? -1)),
   };
   // Weights renormalize over the covered basket; nothing outside it is approximated into it.
   const members = sufficient ? qualifying : [];
@@ -774,6 +914,26 @@ export function buildPortfolioRisk(
       value: regression ? regression.beta * stress.shock * 100 : null,
     };
   });
+  // The given currency and price shocks reprice every line of the book, cash included, at once.
+  const bookLines: RiskBookLine[] = [
+    ...holdings.map((row) => ({
+      id: row.id,
+      label: row.symbol,
+      currency: row.convertedFrom ?? row.currency,
+      // A holding outside the USD marks keeps its gross value, signed as its position is.
+      value: row.value ?? (row.marketValue == null ? null : row.quantity < 0 ? -row.marketValue : row.marketValue),
+      listing: { symbol: row.symbol, exchange: row.exchange },
+    })),
+    ...cashHoldings.map((row) => ({ id: row.id, label: row.symbol, currency: row.currency, value: row.value, listing: null })),
+  ];
+  const repricing = repriceBook(bookLines, portfolio.currency, shifts.fx, shifts.assets);
+  if (repricing?.unmatched.length) {
+    const held = holdings.map((row) => row.symbol);
+    for (const { kind, name } of repricing.unmatched)
+      notes.push(kind === "currency"
+        ? `Nothing in "${portfolio.name}" moves with ${name} against USD, so the ${name} shift changes nothing.`
+        : `"${portfolio.name}" holds no ${name}, so its shift changes nothing${held.length ? `; it holds ${held.slice(0, 8).join(", ")}${held.length > 8 ? ` and ${held.length - 8} more` : ""}` : ""}.`);
+  }
   if (sufficient)
     for (const factor of factors)
       if (factor.samples === 0)
@@ -806,10 +966,15 @@ export function buildPortfolioRisk(
       return {
         ...row,
         percentile: row.rank.percentile,
-        // The method (price returns, bought and held or at fixed current weights) is in docs; the footer keeps room for coverage.
-        detail: filed && row.value == null && TAIL_ROW_IDS.has(row.id) ? `${row.samples} sessions; needs 60` : `${row.samples} sessions`,
+        // The tail rows name how they are estimated; the other rows' method (price returns, bought and held or at fixed current weights) is in docs.
+        detail: TAIL_ROW_IDS.has(row.id) ? riskTailMethod(row.samples, row.value != null) : `${row.samples} sessions`,
         ...(tail
-          ? { amount: (row.value! / 100) * coverage.coveredValue, amountCurrency: coverage.currency, amountBase: coverage.coveredValue }
+          ? {
+              amount: (row.value! / 100) * coverage.coveredValue,
+              amountCurrency: coverage.currency,
+              amountBase: coverage.coveredValue,
+              basis: riskCoverageLine(coverage) ?? undefined,
+            }
           : {}),
       };
     }),
@@ -818,21 +983,48 @@ export function buildPortfolioRisk(
       percentile: row.rank.percentile,
       detail: `${row.samples} sessions; R² ${row.regression?.rSquared?.toFixed(2) ?? "--"}; independent ETF proxy`,
     })),
-    // Largest current value first, left-out holdings in place; unvalued ones last.
-    holdings: [...holdings]
-      .sort((a, b) => (b.marketValue ?? -1) - (a.marketValue ?? -1))
-      .map((row) => ({
-      id: row.id,
-      label: row.symbol,
-      value: row.weight == null ? null : row.weight * 100,
-      unit: "% basket",
-      percentile: null,
-      asOf: row.priceAsOf,
-      detail: row.leftOut
-        ? row.leftOut
-        : `${row.quantity} shares; ${formatNumber(row.value ?? undefined)} ${portfolio.currency}${row.markSource === "close" || row.markSource === "regular-close" ? ` at ${row.priceAsOf} close` : ""}${row.convertedFrom ? ` from ${row.convertedFrom} at daily FX` : ""}; history ${row.historyAsOf}`,
-      ...(row.leftOut ? { leftOut: row.leftOut } : {}),
-    })),
+    // Largest current value first, left-out holdings and each currency's cash in place; unvalued ones last.
+    holdings: [
+      ...holdings.map((row) => ({
+        size: row.marketValue,
+        row: {
+          id: row.id,
+          label: row.symbol,
+          value: row.weight == null ? null : row.weight * 100,
+          unit: "% basket",
+          percentile: null,
+          asOf: row.priceAsOf,
+          detail: row.leftOut
+            ? row.leftOut
+            : `${row.quantity} shares; ${formatNumber(row.value ?? undefined)} ${portfolio.currency}${row.markSource === "close" || row.markSource === "regular-close" ? ` at ${row.priceAsOf} close` : ""}${row.convertedFrom ? ` from ${row.convertedFrom} at daily FX` : ""}; history ${row.historyAsOf}`,
+          ...(row.leftOut ? { leftOut: row.leftOut } : {}),
+        } as RiskDisplayRow,
+      })),
+      ...cashHoldings.map((row) => {
+        const amount = `${formatNumber(row.amount)} ${row.currency}`;
+        const foreign = resolveCurrencyUnit(row.currency).currency !== portfolio.currency;
+        return {
+          size: row.value == null ? null : Math.abs(row.value),
+          row: {
+            id: row.id,
+            label: row.symbol,
+            value: null,
+            unit: "% basket",
+            percentile: null,
+            asOf: market.fetchedAt,
+            // What it is worth in the account currency and what moves it; the value column says it is left out.
+            detail: [
+              !foreign ? amount : row.value == null ? `${amount}; no current ${row.currency} rate values it` : `${amount} = ${formatNumber(row.value)} ${portfolio.currency}`,
+              ...(foreign ? [`moves with ${row.currency}`] : []),
+              "outside the basket",
+            ].join("; "),
+            leftOut: cashReason(row, portfolio.currency),
+          } as RiskDisplayRow,
+        };
+      }),
+    ]
+      .sort((a, b) => (b.size ?? -1) - (a.size ?? -1))
+      .map(({ row }) => row),
     correlation: correlation.map((row) => ({
       id: `${row.left}/${row.right}`,
       label: row.label,
@@ -842,15 +1034,19 @@ export function buildPortfolioRisk(
       asOf: row.asOf ?? null,
       detail: `${row.samples ?? 0} matched daily returns`,
     })),
-    stress: stresses.map((row) => ({
-      id: row.id,
-      label: row.label,
-      value: row.value,
-      unit: "%",
-      percentile: null,
-      asOf: row.regression?.asOf ?? null,
-      detail: `${row.regression?.samples ?? 0} sessions; R² ${row.regression?.rSquared?.toFixed(2) ?? "--"}; ${row.source}`,
-    })),
+    stress: [
+      // A regression scenario moves the basket by its beta; it is a share of the basket, not of the book.
+      ...stresses.map((row) => ({
+        id: row.id,
+        label: row.label,
+        value: row.value,
+        unit: "%",
+        percentile: null,
+        asOf: row.regression?.asOf ?? null,
+        detail: `% of basket; ${row.regression?.samples ?? 0} sessions; R² ${row.regression?.rSquared?.toFixed(2) ?? "--"}; ${row.source}`,
+      })),
+      ...(repricing ? repricingRows(repricing, portfolio.currency, market.fetchedAt) : []),
+    ],
     performance: performance
       ? [
           {
@@ -951,25 +1147,27 @@ export function buildPortfolioRisk(
         )
       : [],
   };
+  // Concentration is of the priced holdings, cash aside, and says so with the value it divides.
+  const holdingsBase = book ? `Share of ${formatNumber(book.gross, 0)} ${portfolio.currency} in priced holdings, cash aside` : "";
   if (book)
     rows.holdings.unshift(
       {
         id: "top",
         label: "Largest holding",
         value: book.top * 100,
-        unit: "% value",
+        unit: HOLDINGS_SHARE_UNIT,
         percentile: null,
         asOf: market.fetchedAt,
-        detail: "Current value of every priced holding",
+        detail: holdingsBase,
       },
       {
         id: "top-five",
         label: "Largest five",
         value: book.topFive * 100,
-        unit: "% value",
+        unit: HOLDINGS_SHARE_UNIT,
         percentile: null,
         asOf: market.fetchedAt,
-        detail: "Current value of every priced holding",
+        detail: holdingsBase,
       },
       {
         id: "hhi",
@@ -978,7 +1176,7 @@ export function buildPortfolioRisk(
         unit: "ratio",
         percentile: null,
         asOf: market.fetchedAt,
-        detail: `${book.effectiveHoldings.toFixed(2)} effective holdings`,
+        detail: `${book.effectiveHoldings.toFixed(2)} effective holdings, cash aside`,
       },
     );
   return {
@@ -997,9 +1195,11 @@ export function buildPortfolioRisk(
     evidence,
     rows,
     coverage,
+    cash: cashHoldings,
+    repricing,
     complete:
       sufficient &&
-      coverage.leftOut.length === 0 &&
+      !riskHoldingsLeftOut(coverage) &&
       metrics.some((row) => row.value != null),
     warnings: [...new Set(warnings)],
     notes,
@@ -1029,18 +1229,11 @@ export const riskValue = (row: RiskDisplayRow) =>
     : row.value == null
     ? "--"
     : `${row.value.toFixed(2)}${row.unit === "%" ? "%" : ` ${row.unit}`}${riskAmount(row)}`;
-/** "220,476 USD basket": the value a tail loss in money is taken on, or null for a row without one. */
-export function riskAmountBase(row: Pick<RiskDisplayRow, "amountBase" | "amountCurrency">): string | null {
-  return row.amountBase != null && Number.isFinite(row.amountBase) && row.amountCurrency
-    ? `${formatNumber(row.amountBase, 0)} ${row.amountCurrency} basket`
-    : null;
-}
-/** A row's evidence with the basket a tail loss in money is taken on. */
+/** A row's evidence with what a tail loss in money is taken on: the basket, its share of the book and what it leaves out. */
 export function riskEvidence(row: RiskDisplayRow): string {
-  const base = riskAmountBase(row);
-  return base ? `${row.detail}; of ${base}` : row.detail;
+  return row.basis ? `${row.detail}; ${row.basis}` : row.detail;
 }
-/** " ($5,735)": a tail loss in money beside its percent. */
+/** " ($5,735)": a loss or change in money beside its percent. */
 function riskAmount(row: RiskDisplayRow): string {
   if (row.amount == null || !Number.isFinite(row.amount) || !row.amountCurrency) return "";
   return ` (${formatCurrency(row.amount, row.amountCurrency, 0)})`;

package/src/plugins/builtin/analytics/risk-options.ts

@@ -6,6 +6,7 @@ import {
   loadScenarioMarket,
   type ScenarioLoaderDependencies,
 } from "../options-scenario/client";
+import { optionModelSpot } from "../options/model-spot";
 import { createGloomberbCloudProvider } from "../../../sources/gloomberb-cloud";
 import { canonicalExchange } from "../../../utils/exchanges";
 
@@ -142,14 +143,28 @@ export async function loadPortfolioOptionBook(
         option.impliedVolatility <= 0
       )
         throw new Error("Contract implied volatility unavailable");
+      // Valued where the chain's IV was measured, as OMON values the chain: a
+      // closed session's quotes at the time they were taken and the session's
+      // close. Over the hours left now, a same-day IV would price the contract
+      // under its quote before the open.
+      const valuation = optionModelSpot(
+        market.underlyingQuote,
+        market.chain,
+        dependencies.now?.() ?? Date.now(),
+        exchange,
+      );
+      if (!valuation)
+        throw new Error(
+          "Fresh matching Cloud spot, chain, rate and dividend inputs are required",
+        );
       const position: ScenarioPosition = {
         symbol: market.symbol,
         exchange,
         currency: market.currency,
-        spot: market.spot,
+        spot: valuation.price,
         rate: market.rate,
         dividendYield: market.dividendYield,
-        asOf: market.asOf,
+        asOf: valuation.valuationTime,
         legs: [
           {
             id: String(contract.conId),