gloomberb 0.18.3 → 0.18.4

package/src/plugins/shortcut-argument.ts

@@ -0,0 +1,39 @@
+import type { HeadlessPaneArgumentKind } from "../types/headless";
+import type { PaneDef, PaneTemplateDef } from "../types/plugin";
+
+type ShortcutArgKind = NonNullable<NonNullable<PaneTemplateDef["shortcut"]>["argKind"]>;
+
+const SHORTCUT_ARG_KINDS: Record<Exclude<HeadlessPaneArgumentKind, "none">, ShortcutArgKind> = {
+  ticker: "ticker",
+  tickers: "ticker-list",
+  "symbol-list": "ticker-list",
+  "free-text": "text",
+};
+
+/**
+ * The template as the command bar reads it. A shortcut that declares no
+ * argument takes the one the function declares for `fn` and `catalog`
+ * (`headless.argument`), so `PF Book` opens Book in the bar as it does in
+ * `gloom fn PF Book`. A shortcut that declares its own argument keeps it.
+ */
+export function withFunctionShortcutArgument(
+  template: PaneTemplateDef,
+  pane?: Pick<PaneDef, "headless">,
+): PaneTemplateDef {
+  const shortcut = template.shortcut;
+  if (!shortcut || shortcut.argKind || shortcut.argPlaceholder) return template;
+  const argument = (template.headless ?? pane?.headless)?.argument;
+  if (!argument || argument.kind === "none") return template;
+  const argKind = SHORTCUT_ARG_KINDS[argument.kind];
+  const argPlaceholder = argument.placeholder
+    ?? (argKind === "ticker" ? "ticker" : argKind === "ticker-list" ? "tickers" : undefined);
+  return {
+    ...template,
+    shortcut: {
+      ...shortcut,
+      argKind,
+      ...(argPlaceholder ? { argPlaceholder } : {}),
+      ...(argument.optional ? { argOptional: true } : {}),
+    },
+  };
+}

package/src/portfolio/allocation.ts

@@ -6,7 +6,7 @@ import { parseTypedNumber } from "../utils/decimal-comma";
 
 /**
  * Weights, targets and the trades that would rebalance a portfolio. `PF`, its
- * `fn PF` report and `gloomberb portfolio show` all read these figures from
+ * `fn PF` report and `gloom portfolio show` all read these figures from
  * here, so a weight never differs between them.
  *
  * A weight is a share of the total value, cash included: the priced holdings

package/src/portfolio/collection-name.ts

@@ -1,5 +1,9 @@
+import type { ShortcutArgError } from "../types/plugin";
+
 /** Collections an unknown-name error lists, so the caller can retry with one. */
 const LISTED_COLLECTIONS = 12;
+/** Names the command bar lists under an unknown one: they share one row of the bar. */
+const LISTED_COLLECTION_NAMES = 6;
 
 /**
  * The portfolio or watchlist an argument names, by its id or its name,
@@ -21,6 +25,33 @@ export function findNamedCollection<T extends { id: string; name: string }>(
   )) ?? null;
 }
 
+/**
+ * The command bar's row for a function typed with a portfolio or watchlist
+ * nothing has (`PF Nope`, `PORT Nope`), or null when one of `collections` has
+ * that name or id. `noun` says what was looked for; `form` writes each name
+ * the way the function takes it (`PORT:Book` for EXPO).
+ */
+export function unknownCollectionArgError(
+  raw: string,
+  collections: readonly { id: string; name: string }[],
+  noun: "portfolio" | "watchlist" | "portfolio or watchlist",
+  form: (name: string) => string = (name) => name,
+): ShortcutArgError | null {
+  const wanted = raw.trim();
+  if (findNamedCollection(collections, wanted)) return null;
+  const names = collections.map((collection) => form(collection.name.trim() || collection.id));
+  const listed = names.slice(0, LISTED_COLLECTION_NAMES);
+  const more = names.length - listed.length;
+  const plural = noun === "portfolio or watchlist" ? "portfolios or watchlists" : `${noun}s`;
+  return {
+    message: `No ${noun} named "${wanted}"`,
+    detail: listed.length === 0 ? `No ${plural} are set up`
+      : more > 0 ? `Try ${listed.join(", ")} or ${more} more`
+      : listed.length === 1 ? `Try ${listed[0]}`
+      : `Try ${listed.slice(0, -1).join(", ")} or ${listed.at(-1)}`,
+  };
+}
+
 /** "Main Portfolio (main), Family (family)": each collection's name and id, for an error naming what there is. */
 export function describeCollections(collections: readonly { id: string; name: string }[]): string {
   const listed = collections.slice(0, LISTED_COLLECTIONS).map(({ id, name }) => (

package/src/portfolio/column-values.ts

@@ -3,7 +3,7 @@
 import { comparablePriceEarnings, formatPriceEarnings } from "../utils/price-earnings";
 import { convertMarketCapitalization, listedMarketCapitalization } from "../utils/market-capitalization";
 import type { ColumnConfig } from "../types/config";
-import type { AnalystResearchData, CorporateActionsData, MarketState, TickerFinancials } from "../types/financials";
+import type { AnalystResearchData, CorporateActionsData, MarketState, Quote, TickerFinancials } from "../types/financials";
 import type { EarningsEvent } from "../types/data-provider";
 import type { TickerRecord } from "../types/ticker";
 import { colors, priceColor } from "../theme/colors";
@@ -37,6 +37,7 @@ import { distributionHistory, forwardYieldMayHaveLapsed, lapsedDividend } from "
 import { classifyInstrumentType } from "../tickers/instrument-kind";
 import { isIndexLevel, reportedQuoteVolume } from "../market-data/market/index-level";
 import { perpetualDisplaySymbol, perpetualListing } from "../tickers/perpetual-listing";
+import { premiumToUnderlying, type PerpetualPremiumRow } from "../market-data/perpetual-premium";
 import { currentListingName } from "../tickers/listing-name";
 import { PRICE_SPARKLINE_COLUMN_ID } from "../components/price-sparkline/view";
 import { followLiveSparklinePrice, resolveSparklineHistory, sparklineValues } from "../components/price-sparkline/model";
@@ -117,10 +118,8 @@ export interface ColumnContext {
 }
 
 /** A row's stock perpetual as PERP% and FUND 8H read it; rates are fractions. */
-interface ListedPerpetual {
+interface ListedPerpetual extends PerpetualPremiumRow {
   marketId: string;
-  /** The mark over the stock's last price; null without a comparable reference. */
-  underlyingPremium: number | null;
   /** Funding per eight hours, whatever interval the venue pays on. */
   fundingRate8h: number | null;
   /** The venue's latest reading is old. */
@@ -136,9 +135,12 @@ export function formatPerpetualRate(value: number, decimals: number): string {
   return `${/[1-9]/.test(fixed) ? (value > 0 ? "+" : "-") : ""}${fixed}%`;
 }
 
-function perpetualValue(columnId: keyof typeof PERPETUAL_FIELDS, symbol: string, ctx: ColumnContext): { pending: boolean; data: ListedPerpetual | null; value: number | null } {
+/** PERP% is against the row's own stock quote while that is live (premiumToUnderlying). */
+function perpetualValue(columnId: keyof typeof PERPETUAL_FIELDS, symbol: string, ctx: ColumnContext, quote: Quote | undefined): { pending: boolean; data: ListedPerpetual | null; value: number | null } {
   const perp = mapData(ctx.perpetuals, symbol);
-  return { ...perp, value: perp.data?.[PERPETUAL_FIELDS[columnId]] ?? null };
+  const value = !perp.data ? null
+    : columnId === "perp_premium" ? premiumToUnderlying(perp.data, quote) : perp.data[PERPETUAL_FIELDS[columnId]];
+  return { ...perp, value: value ?? null };
 }
 
 /** Position and calendar dates as "Jan 5", read in UTC. */
@@ -644,7 +646,7 @@ export function getColumnValue(
     }
     case "perp_premium":
     case "perp_funding": {
-      const perp = perpetualValue(col.id, ticker.metadata.ticker, ctx);
+      const perp = perpetualValue(col.id, ticker.metadata.ticker, ctx, quote);
       if (perp.pending) return { text: "…" };
       if (perp.value == null) return { text: "—" };
       // An old venue reading keeps its figure, dimmed, as PERP shows a stale market.
@@ -823,7 +825,7 @@ export function getSortValue(
     }
     case "perp_premium":
     case "perp_funding":
-      return perpetualValue(col.id, ticker.metadata.ticker, ctx).value;
+      return perpetualValue(col.id, ticker.metadata.ticker, ctx, quote).value;
     case "latency":
       return quote ? ctx.now - (resolveQuoteAgeTimestamp(quote, ctx.now) ?? ctx.now) : null;
     case "as_of":

package/src/portfolio/cost-fx.ts

@@ -1,6 +1,13 @@
-import { fxLegForCurrency } from "../market-data/coordinator/fx-legs";
-import { fxCloseOnDate, type FxHistoryClient } from "../market-data/fx-closes";
-import { heldCurrencyUnit } from "../utils/currency-units";
+import type { FxLeg } from "../market-data/coordinator/fx-legs";
+import { dailyFxLeg, readFxCloseOnDate, type FxHistoryClient } from "../market-data/fx-closes";
+import { formatFxRate } from "../cli/fx-pair";
+import { dateOptionError, readCalendarDate } from "../utils/calendar-date";
+import { currencyUnitLabel, heldCurrencyUnit } from "../utils/currency-units";
+import { readTypedNumber } from "../utils/decimal-comma";
+import { logFailure } from "../utils/log-failure";
+import { mapWithConcurrency } from "../utils/concurrency";
+import type { TickerPosition, TickerRecord } from "../types/ticker";
+import { lotCostFxRate, sameCurrency } from "./position-metrics";
 
 /** Reads a pair's daily bars; `apiClient` in the app, a fake in tests. */
 export type CostFxHistoryClient = FxHistoryClient;
@@ -20,24 +27,54 @@ export class CostFxError extends Error {
   }
 }
 
+/** A dated close, and whether the service keeps daily bars of any pair it was looked for in. */
+interface PairCloseRead {
+  reading: CostFxReading | null;
+  served: boolean;
+}
+
+/** The daily pair BASE/QUOTE as `history` asks for it (USD/THB is USDTHB=X), read as QUOTE per BASE, or inverted. */
+const fxPair = (base: string, quote: string, invert: boolean): FxLeg =>
+  ({ currency: base, instrument: { symbol: `${base}${quote}=X`, exchange: "" }, invert });
+
+/**
+ * The close in the week up to `date` of the first of the pairs, tried in
+ * order, that the service keeps daily bars of; the next is asked only when
+ * one is not served at all, as a served pair with no close that week is a
+ * gap the same pair the other way round has too.
+ */
+async function firstPairClose(pairs: readonly FxLeg[], date: string, client: CostFxHistoryClient, now: Date): Promise<PairCloseRead> {
+  for (const pair of pairs) {
+    const read = await readFxCloseOnDate(pair, date, client, now);
+    if (read.reading || read.served) return read;
+  }
+  return { reading: null, served: false };
+}
+
 /**
  * USD per unit of an ISO currency at its last completed daily close on or
- * before `date`, looking back a week at most (`fxCloseOnDate`, as `fx --date`
- * reads it). Null when the pair has no close in that week.
+ * before `date`, looking back a week at most, as `fx --date` reads it: its
+ * dollar pair as markets quote it (`dailyFxLeg`: EUR/USD, USD/THB), else the
+ * same pair the other way round, as `history` serves either.
  */
-async function usdPerUnitOn(code: string, date: string, client: CostFxHistoryClient, now: Date): Promise<CostFxReading | null> {
-  if (code === "USD") return { rate: 1, date };
-  const leg = fxLegForCurrency(code);
-  if (!leg) throw new CostFxError(`No daily FX history is served for ${code}`);
-  return fxCloseOnDate(leg, date, client, now);
+async function usdPerUnitOn(code: string, date: string, client: CostFxHistoryClient, now: Date): Promise<PairCloseRead> {
+  if (code === "USD") return { reading: { rate: 1, date }, served: true };
+  const quoted = dailyFxLeg(code);
+  if (!quoted) return { reading: null, served: false };
+  const other = quoted.invert ? fxPair(code, "USD", false) : fxPair("USD", code, true);
+  return firstPairClose([quoted, other], date, client, now);
 }
 
 /**
  * What one unit of `from` (a lot's currency, GBp counting pence and USX cents) cost in
  * `into` (the portfolio's) at the daily FX closes of `date`, each pair's last
- * close on or before it, crossed through USD as every converted value is.
- * Throws `CostFxError` when a pair is not served or has no close in the week
- * before the date.
+ * close on or before it: crossed through USD as every converted value is,
+ * each dollar pair read either way round, and for two currencies neither of
+ * which is the dollar, their own pair (either way round) when a dollar pair
+ * is not served. No currency is left out for not being on a list: any pair
+ * `history` serves is read. Throws `CostFxError` when none of them has a
+ * close in the week before the date, saying when a currency has no daily
+ * history served at all.
  */
 export async function loadCostFxRate(
   from: string,
@@ -48,14 +85,254 @@ export async function loadCostFxRate(
 ): Promise<CostFxReading> {
   const fromUnit = heldCurrencyUnit(from);
   const intoUnit = heldCurrencyUnit(into);
+  // A minor unit (GBp, USX) is that fraction of its major currency's rate.
+  const units = intoUnit.divisor / fromUnit.divisor;
+  if (fromUnit.currency === intoUnit.currency) return { rate: units, date };
   const [fromUsd, intoUsd] = await Promise.all([
     usdPerUnitOn(fromUnit.currency, date, client, now),
     usdPerUnitOn(intoUnit.currency, date, client, now),
   ]);
-  const missing = [fromUsd ? null : fromUnit.currency, intoUsd ? null : intoUnit.currency].filter(Boolean);
-  if (!fromUsd || !intoUsd) throw new CostFxError(`No ${missing.join(" or ")} FX close in the week up to ${date}`);
-  const rate = (fromUsd.rate / fromUnit.divisor) / (intoUsd.rate / intoUnit.divisor);
-  if (!Number.isFinite(rate) || rate <= 0) throw new CostFxError(`No usable ${fromUnit.currency}/${intoUnit.currency} rate for ${date}`);
-  // A pair that did not trade that day (its holiday) dates the cross by its own last close.
-  return { rate, date: fromUsd.date < intoUsd.date ? fromUsd.date : intoUsd.date };
+  let reading: CostFxReading | null = null;
+  let crossServed = false;
+  if (fromUsd.reading && intoUsd.reading) {
+    // A pair that did not trade that day (its holiday) dates the cross by its own last close.
+    reading = {
+      rate: (fromUsd.reading.rate / intoUsd.reading.rate) * units,
+      date: fromUsd.reading.date < intoUsd.reading.date ? fromUsd.reading.date : intoUsd.reading.date,
+    };
+  } else if (fromUnit.currency !== "USD" && intoUnit.currency !== "USD" && (!fromUsd.served || !intoUsd.served)) {
+    const direct = await firstPairClose([
+      fxPair(fromUnit.currency, intoUnit.currency, false),
+      fxPair(intoUnit.currency, fromUnit.currency, true),
+    ], date, client, now);
+    if (direct.reading) reading = { rate: direct.reading.rate * units, date: direct.reading.date };
+    crossServed = direct.served;
+  }
+  if (!reading) {
+    const missing = [[fromUnit.currency, fromUsd], [intoUnit.currency, intoUsd]] as const;
+    const unserved = missing.filter(([, read]) => !read.reading && !read.served).map(([code]) => code);
+    if (unserved.length > 0 && !crossServed) throw new CostFxError(`No daily FX history is served for ${unserved.join(" or ")}`);
+    const late = missing.filter(([, read]) => !read.reading).map(([code]) => code);
+    throw new CostFxError(`No ${late.join(" or ")} FX close in the week up to ${date}`);
+  }
+  if (!Number.isFinite(reading.rate) || reading.rate <= 0) {
+    throw new CostFxError(`No usable ${fromUnit.currency}/${intoUnit.currency} rate for ${date}`);
+  }
+  return reading;
+}
+
+/** A lot's currency as a portfolio values it: its own, else its listing's. */
+const lotCurrency = (ticker: TickerRecord, position: TickerPosition) => (position.currency || ticker.metadata.currency || "").trim();
+const purchaseDateKey = (currency: string, date: string) => `${currency}|${date}`;
+
+/**
+ * Whether a lot's cost converts at the FX close of its purchase date when it
+ * is valued in `into`: entered by hand, dated, held in another currency, and
+ * with no rate of its own into `into` (one given with --cost-fx, or read for
+ * its date when the portfolio was valued in `into` before). A broker's lot
+ * reads as it always has.
+ */
+function convertsAtPurchaseDate(position: TickerPosition, currency: string, into: string, portfolioId?: string): boolean {
+  return position.broker === "manual" && position.shares !== 0 && (!portfolioId || position.portfolio === portfolioId)
+    && !!currency && !sameCurrency(currency, into) && /^\d{4}-\d{2}-\d{2}$/.test(position.dateAcquired ?? "")
+    && lotCostFxRate(position, currency, into) === null;
+}
+
+/** One unit of a lot's currency in the valuation's at the close of its purchase date, by currency and date. */
+export type PurchaseDateCostFx = ReadonlyMap<string, CostFxReading>;
+
+/** Purchase dates whose FX closes are read at once. */
+const PURCHASE_DATE_READS = 4;
+
+/** The lot currencies and purchase dates whose FX closes a portfolio valued in `into` converts costs at, by key. */
+export function purchaseDatesToRead(tickers: readonly TickerRecord[], into: string, portfolioId?: string): Map<string, { currency: string; date: string }> {
+  const dates = new Map<string, { currency: string; date: string }>();
+  for (const ticker of tickers) {
+    for (const position of ticker.metadata.positions) {
+      const currency = lotCurrency(ticker, position);
+      if (!convertsAtPurchaseDate(position, currency, into, portfolioId)) continue;
+      dates.set(purchaseDateKey(currency, position.dateAcquired!), { currency, date: position.dateAcquired! });
+    }
+  }
+  return dates;
+}
+
+/**
+ * The FX closes of the purchase dates of a portfolio's lots that convert at
+ * them (convertsAtPurchaseDate) when valued in `into`, read as `position set
+ * --date` reads one: each pair's last close on or before the date, a week
+ * back at most. A date whose closes cannot be read is left out, so its lots'
+ * cost converts at today's rate.
+ */
+export async function loadPurchaseDateCostFx(
+  tickers: readonly TickerRecord[],
+  { into, history, portfolioId, now = new Date() }: { into: string; history: CostFxHistoryClient; portfolioId?: string; now?: Date },
+): Promise<Map<string, CostFxReading>> {
+  const dates = purchaseDatesToRead(tickers, into, portfolioId);
+  const readings = await mapWithConcurrency([...dates], PURCHASE_DATE_READS, async ([key, { currency, date }]) =>
+    [key, await loadCostFxRate(currency, into, date, history, now)
+      .catch(logFailure("portfolio.cost-fx", "Reading a purchase date's FX close failed", null))] as const);
+  return new Map(readings.filter((entry): entry is readonly [string, CostFxReading] => entry[1] != null));
+}
+
+/**
+ * The tickers with each lot that converts at its purchase date's FX close
+ * given that rate into `into`, so its cost and P&L carry the currency's move
+ * since it was bought. For valuing only, never saved: the same array and
+ * records where nothing changes.
+ */
+export function withPurchaseDateCostFx(tickers: readonly TickerRecord[], rates: PurchaseDateCostFx, into: string, portfolioId?: string): TickerRecord[] {
+  if (rates.size === 0) return tickers as TickerRecord[];
+  let changed = false;
+  const dated = tickers.map((ticker) => {
+    let touched = false;
+    const positions = ticker.metadata.positions.map((position) => {
+      const currency = lotCurrency(ticker, position);
+      const reading = convertsAtPurchaseDate(position, currency, into, portfolioId)
+        ? rates.get(purchaseDateKey(currency, position.dateAcquired!)) : undefined;
+      if (!reading) return position;
+      touched = true;
+      return { ...position, costFxRate: reading.rate, costFxCurrency: into.trim() };
+    });
+    if (!touched) return ticker;
+    changed = true;
+    return { ...ticker, metadata: { ...ticker.metadata, positions } };
+  });
+  return changed ? dated : tickers as TickerRecord[];
+}
+
+/** How the command line or the position form names the purchase date and the rate in what it says. */
+export interface CostFxWording {
+  /** The rate's option or field: `--cost-fx`, Cost FX. */
+  rate: string;
+  /** The date's option or field as a date error names it: `--date`, or empty for a form field. */
+  dateOption: string;
+  /** The date's option or field as a sentence names it: `--date`, Purchase Date. */
+  date: string;
+  /** Where to give the rate instead, for a pair such as `TRY per USD`. */
+  rateInstead(pair: string): string;
+  /** That the purchase date gives the rate too. */
+  dateInstead: string;
+}
+
+export const CLI_COST_FX_WORDING: CostFxWording = {
+  rate: "--cost-fx",
+  dateOption: "--date",
+  date: "--date",
+  rateInstead: (pair) => `Give the rate it was bought at instead: --cost-fx <${pair}>.`,
+  dateInstead: "Or give the purchase --date, and its daily FX close is used.",
+};
+
+export const FORM_COST_FX_WORDING: CostFxWording = {
+  rate: "Cost FX",
+  dateOption: "",
+  date: "Purchase Date",
+  rateInstead: (pair) => `Give the rate it was bought at in Cost FX instead, in ${pair}.`,
+  dateInstead: "Or give the Purchase Date, and its daily FX close is used.",
+};
+
+/** A purchase date or cost FX rate that cannot be used, and what to give instead. */
+export class PositionCostFxError extends Error {
+  constructor(message: string, readonly details?: string) {
+    super(message);
+    this.name = "PositionCostFxError";
+  }
+}
+
+/**
+ * A typed purchase date as an ISO day, no later than today (UTC); throws
+ * saying which formats it takes.
+ */
+export function readPurchaseDate(value: string, wording: CostFxWording, now = new Date()): string {
+  const date = readCalendarDate(value);
+  if (!date) throw new PositionCostFxError(dateOptionError(value, wording.dateOption, { subject: "the purchase date", now }));
+  if (date > now.toISOString().slice(0, 10)) {
+    throw new PositionCostFxError(`${wording.date} ${value.trim()} is after today; it is the day the position was bought.`);
+  }
+  return date;
+}
+
+/** A typed cost FX rate: a positive number, 32,15 read as 32.15; throws otherwise. */
+export function readCostFxRate(value: string, wording: CostFxWording): number {
+  const rate = readTypedNumber(value, wording.rate);
+  if (!Number.isFinite(rate) || rate <= 0) {
+    throw new PositionCostFxError(`${wording.rate} is the rate the cost was bought at, a positive number such as 32.15 (TRY per USD); got "${value.trim()}".`);
+  }
+  return rate;
+}
+
+/**
+ * The rate a position's cost was bought at, as typed or from the FX closes of
+ * its purchase date, for a position held in another currency than the
+ * portfolio's; undefined when neither was given or the position is in the
+ * portfolio's currency (a date alone then only dates the lot). A rate typed
+ * for a position in the portfolio's own currency, one that reads as a
+ * mistake against today's, and a date with no FX close throw
+ * PositionCostFxError saying what to give instead.
+ */
+export async function resolvePositionCostFx({ date, costFx, history, currency, portfolioCurrency, listing, todaysRate, wording }: {
+  date?: string; costFx?: number; history: CostFxHistoryClient; currency: string; portfolioCurrency: string; listing: string;
+  /** Today's rate, one unit of `currency` in `portfolioCurrency`; NaN when it cannot be read. */
+  todaysRate: () => Promise<number>;
+  wording: CostFxWording;
+}): Promise<{ costFx: { rate: number; currency: string }; date: string | null } | undefined> {
+  const foreign = !sameCurrency(currency, portfolioCurrency);
+  const insteadHint = wording.rateInstead(`${portfolioCurrency} per ${currency}`);
+  if (costFx != null) {
+    if (!foreign) {
+      const held = currency === portfolioCurrency ? currency : `${currency}, a unit of ${portfolioCurrency}`;
+      throw new PositionCostFxError(`${wording.rate} converts a cost in another currency; ${listing} is held in ${held}, the portfolio's currency.`);
+    }
+    const today = await todaysRate().catch(logFailure("portfolio.cost-fx", "Reading today's rate to check a typed cost FX rate failed", Number.NaN));
+    const problem = implausibleCostFx(costFx, today, { currency, portfolioCurrency, listing, wording });
+    if (problem) throw new PositionCostFxError(problem, wording.dateInstead);
+    return { costFx: { rate: costFx, currency: portfolioCurrency }, date: null };
+  }
+  if (!date || !foreign) return undefined;
+  try {
+    const reading = await loadCostFxRate(currency, portfolioCurrency, date, history);
+    return { costFx: { rate: reading.rate, currency: portfolioCurrency }, date: reading.date };
+  } catch (error) {
+    if (error instanceof CostFxError) {
+      throw new PositionCostFxError(`${error.message}, so the ${currency} cost cannot be converted at the rate of ${date}.`, insteadHint);
+    }
+    // Offline, signed out or a server error: say what was being read, and the way that needs no network.
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new PositionCostFxError(`Could not read the ${currency} and ${portfolioCurrency} FX closes of ${date}: ${reason}.`, insteadHint);
+  }
+}
+
+/** How far from today's rate a typed one may be: a currency that lost 99% since purchase still fits. */
+const COST_FX_MAX_RATIO = 100;
+
+/**
+ * Why a typed cost FX rate reads as a mistake against today's rate, else null:
+ * a rate per pound for a lot held in pence, the inverse of the pair (0.0319
+ * for 31.37 TRY per USD), or more than a hundred times off either way. A
+ * rate is only called inverted when today's is far from 1 and the typed one
+ * lies on the other side of it, so EUR per USD near parity is never refused.
+ * Null when today's rate is not known.
+ */
+function implausibleCostFx(
+  rate: number,
+  today: number,
+  { currency, portfolioCurrency, listing, wording }: { currency: string; portfolioCurrency: string; listing: string; wording: CostFxWording },
+): string | null {
+  if (!Number.isFinite(today) || today <= 0) return null;
+  const pair = `${portfolioCurrency} per ${currency}`;
+  const typed = formatFxRate(rate);
+  const todays = `today's is ${formatFxRate(today)} ${pair}`;
+  const unit = heldCurrencyUnit(currency);
+  if (unit.divisor !== 1 && rate / today >= unit.divisor / 5 && rate / today <= unit.divisor * 5) {
+    const name = currency.toUpperCase() === "USX" ? "US cents" : currencyUnitLabel(currency).replace(/^\S+ \((.+)\)$/, "$1");
+    return `${wording.rate} ${typed} looks like ${portfolioCurrency} per ${unit.currency}; ${listing} is held in ${currency} (${name}), `
+      + `so the rate is ${pair}, 1/${unit.divisor} of that: ${todays}.`;
+  }
+  if ((today >= 3 && rate < 1) || (today <= 1 / 3 && rate > 1)) {
+    return `${wording.rate} ${typed} looks inverted: it is the ${portfolioCurrency} paid for one ${currency}, and ${todays}.`;
+  }
+  if (rate / today > COST_FX_MAX_RATIO || today / rate > COST_FX_MAX_RATIO) {
+    return `${wording.rate} ${typed} is more than ${COST_FX_MAX_RATIO} times off today's rate (${formatFxRate(today)} ${pair}); check the rate.`;
+  }
+  return null;
 }

package/src/portfolio/manual-lots.ts

@@ -1,4 +1,6 @@
 import type { TickerPosition, TickerRecord } from "../types/ticker";
+import { normalizeHeldCurrencyCode } from "../utils/currency-units";
+import { parseDisplayDate } from "../utils/datetime-format";
 import { signedPositionDirection } from "./position-metrics";
 
 /** The ticker's manual lots in one portfolio, in saved order. */
@@ -19,6 +21,74 @@ export interface ManualPortfolioPositionPrefill {
   position: TickerPosition | null;
   /** The currencies of several lots that disagree. They are not totalled across currencies. */
   currencies?: string[];
+  /** Why several lots' cost FX rates do not become the position's one rate; the position then has none. */
+  costFxConflict?: LotCostFxConflict;
+}
+
+/**
+ * Why the cost FX rates of several lots cannot become one: some lots convert
+ * their cost at the rate they were bought at and some at today's, the lots are
+ * in different currencies, or their rates convert into different currencies.
+ */
+export type LotCostFxConflict = "todays-rate" | "lot-currencies" | "rate-currencies";
+
+export interface MergedLotCostTerms {
+  /** The earliest purchase date of the lots that have one. */
+  dateAcquired?: string;
+  /** One unit of `currency` in `costFx.currency`, weighted so the position's cost converts to what the lots' costs did. */
+  costFx?: { rate: number; currency: string };
+  /** The lots' common currency, the one `costFx` is a rate of. */
+  currency?: string;
+  costFxConflict?: LotCostFxConflict;
+}
+
+function lotCostFx(lot: TickerPosition): { rate: number; currency: string } | null {
+  const rate = lot.costFxRate;
+  const currency = lot.costFxCurrency?.trim().toUpperCase();
+  return typeof rate === "number" && Number.isFinite(rate) && rate > 0 && currency ? { rate, currency } : null;
+}
+
+/**
+ * The purchase date and cost FX rate several lots keep when they become one
+ * position (a set over several lots, or a team's new count collapsing them):
+ *
+ * - The date is the earliest of the lots': the PF ACQ and HELD columns read the
+ *   earliest lot already, so it reads the same after the merge.
+ * - The rate is the lots' rates weighted by each lot's cost (shares times
+ *   average cost), so the position's cost converts to exactly what the lots'
+ *   costs did; by shares when a lot has no cost, there being no cost to keep.
+ *
+ * A rate is kept only when it is honest: every held lot has one, into one
+ * currency, and the lots share a currency. Otherwise `costFxConflict` says why
+ * and there is no rate. A lot of no shares weighs nothing and blocks nothing.
+ */
+export function mergeLotCostTerms(lots: readonly TickerPosition[]): MergedLotCostTerms {
+  const dated = lots
+    .map((lot) => ({ value: lot.dateAcquired, time: parseDisplayDate(lot.dateAcquired)?.getTime() }))
+    .filter((entry): entry is { value: string; time: number } => !!entry.value && entry.time != null)
+    .sort((left, right) => left.time - right.time)[0];
+  const date = dated ? { dateAcquired: dated.value } : {};
+  const nonzero = lots.filter((lot) => lot.shares !== 0);
+  const held = nonzero.length > 0 ? nonzero : lots;
+  const currencies = new Set(held.map((lot) => normalizeHeldCurrencyCode(lot.currency)));
+  const currency = currencies.size === 1 ? { currency: [...currencies][0]! } : {};
+  const rates = held.map(lotCostFx);
+  const rated = rates.filter((rate): rate is { rate: number; currency: string } => rate !== null);
+  if (rated.length === 0) return { ...date, ...currency };
+  if (rated.length < held.length) return { ...date, ...currency, costFxConflict: "todays-rate" };
+  if (currencies.size > 1) return { ...date, costFxConflict: "lot-currencies" };
+  const into = new Set(rated.map((rate) => rate.currency));
+  if (into.size > 1) return { ...date, ...currency, costFxConflict: "rate-currencies" };
+  const costFxCurrency = rated[0]!.currency;
+  if (rated.every((rate) => rate.rate === rated[0]!.rate)) return { ...date, ...currency, costFx: { rate: rated[0]!.rate, currency: costFxCurrency } };
+  const costs = held.map((lot) => Math.abs(lot.shares) * (lot.avgCost ?? Number.NaN));
+  const costed = costs.every((cost) => Number.isFinite(cost) && cost >= 0) && costs.some((cost) => cost > 0);
+  const weights = costed ? costs : held.map((lot) => Math.abs(lot.shares));
+  const total = weights.reduce((sum, weight) => sum + weight, 0);
+  const rate = tidyNumber(weights.reduce((sum, weight, index) => sum + weight * rated[index]!.rate, 0) / total);
+  return Number.isFinite(rate) && rate > 0
+    ? { ...date, ...currency, costFx: { rate, currency: costFxCurrency } }
+    : { ...date, ...currency, costFxConflict: "todays-rate" };
 }
 
 /** Drops the float noise of a sum (0.1 + 0.2) without losing a digit anyone entered. */
@@ -63,6 +133,8 @@ export function getManualPortfolioPositionPrefill(ticker: TickerRecord, portfoli
     ? tidyNumber(lots.reduce((sum, lot) => sum + Math.abs(lot.shares) * lot.avgCost!, 0) / magnitude)
     : undefined;
   const multiplier = held[0]!.multiplier;
+  // The purchase date and the rate the cost was bought at carry over as mergeLotCostTerms keeps them.
+  const terms = mergeLotCostTerms(lots);
   return {
     lotCount,
     position: {
@@ -72,7 +144,10 @@ export function getManualPortfolioPositionPrefill(ticker: TickerRecord, portfoli
       // Lots that name no currency stay without one, as a single such lot does.
       ...(currencies[0] && lots.some((lot) => lot.currency?.trim()) ? { currency: currencies[0] } : {}),
       broker: "manual",
+      ...(terms.dateAcquired ? { dateAcquired: terms.dateAcquired } : {}),
+      ...(terms.costFx ? { costFxRate: terms.costFx.rate, costFxCurrency: terms.costFx.currency } : {}),
       ...(multiplier !== undefined ? { multiplier } : {}),
     },
+    ...(terms.costFxConflict ? { costFxConflict: terms.costFxConflict } : {}),
   };
 }