@insiderfinance/totalfinance 0.1.0

package/modules/options/src/equity-lattice.ts

@@ -0,0 +1,224 @@
+/**
+ * Generic equity binomial lattice (spec §9 lattice tooling). A reusable Cox–Ross–Rubinstein /
+ * Jarrow–Rudd tree on a single GBM underlying, exposing a `rollback` primitive that hands each node its
+ * two child values and full context (spot, time, up-probability, per-step discount). Unlike the
+ * option-specific lattice engines, this is payoff-agnostic: American/Bermudan equity exotics and
+ * credit-adjusted instruments (convertible bonds) supply their own node logic. Pure and clock-free.
+ */
+
+import {
+  ensureKnownKeys,
+  ensureFiniteWhenPresent,
+  ErrorCode,
+  InputError,
+  ensureFinite,
+  ensurePositive,
+  requireArgumentObject,
+} from '@totalfinance/core';
+
+export type LatticeVariant = 'crr' | 'jarrow-rudd';
+
+/**
+ * The most time steps one lattice will carry (2026-08-23 review, P0 "unbounded work"):
+ * `Number.isInteger(1e308)` is `true`, so the old check admitted a step count whose `rollback`
+ * could never finish — the tree has steps²/2 nodes, each a `combine` callback (measured ~24 ns/node
+ * for a plain closure: 25,000 steps ≈ 3.1×10^8 nodes ≈ 8 s, the single-digit-second ceiling). The
+ * cap still clears the documented CRR-stability requirement `steps > (horizonYears·(rate−q)/σ)²`
+ * for extreme drift/vol ratios (e.g. rate 1.0, σ 0.01 needs > 10^4), and CRR pricing error is
+ * O(1/steps) — long converged by 25,000.
+ */
+const MAX_LATTICE_STEPS = 25_000;
+
+export interface EquityLatticeOptions {
+  spot: number;
+  riskFreeRate: number;
+  dividendYield?: number;
+  volatility: number;
+  /** Horizon in years. */
+  horizonYears: number;
+  /** Number of time steps (default 200). */
+  steps?: number;
+  /** `crr` (Cox–Ross–Rubinstein, default) or `jarrow-rudd` (equal-probability). */
+  variant?: LatticeVariant;
+}
+
+/** Per-node context handed to a {@link EquityLattice.rollback} combiner. */
+export interface LatticeNode {
+  /** Time step index (0 = today). */
+  stepIndex: number;
+  /** Up-move count at the node (`0..stepIndex`). */
+  upMoveCount: number;
+  /** Underlying price at the node. */
+  spot: number;
+  /** Node time in years (`i·dt`). */
+  timeToExpiryYears: number;
+  /** Continuation value from the upper child. */
+  up: number;
+  /** Continuation value from the lower child. */
+  down: number;
+  /** Risk-neutral up-probability. */
+  upProbability: number;
+  /** Per-step discount factor `e^{−r·dt}`. */
+  discount: number;
+  /** Step length in years. */
+  timeStepYears: number;
+}
+
+export interface EquityLattice {
+  readonly steps: number;
+  readonly timeStepYears: number;
+  /** Up-probability (risk-neutral). */
+  readonly upProbability: number;
+  /** Underlying price at node `(stepIndex, upMoveCount)` (`upMoveCount` up-moves out of `stepIndex`). */
+  spotAt(stepIndex: number, upMoveCount: number): number;
+  /**
+   * Backward induction from the terminal step to the root. `terminal(spot)` seeds each leaf; `combine`
+   * returns each interior node's value from its children + context (apply discounting, exercise,
+   * conversion, default adjustment — whatever the instrument needs). Returns the root value.
+   */
+  rollback(terminal: (spot: number) => number, combine: (node: LatticeNode) => number): number;
+}
+
+/** Build a Cox–Ross–Rubinstein / Jarrow–Rudd equity binomial lattice. */
+export function equityLattice(options: EquityLatticeOptions): EquityLattice {
+  requireArgumentObject('equityLattice', 'options', options);
+  const functionName = 'equityLattice';
+  ensureKnownKeys(functionName, 'options', options, [
+    'spot',
+    'riskFreeRate',
+    'dividendYield',
+    'volatility',
+    'horizonYears',
+    'steps',
+    'variant',
+  ]);
+  ensurePositive(options.spot, 'spot', functionName);
+  ensurePositive(options.volatility, 'volatility', functionName);
+  ensurePositive(options.horizonYears, 'horizonYears', functionName);
+  ensureFinite(options.riskFreeRate, 'riskFreeRate', functionName);
+  // Null is a wrong-typed value, not omission (the 350c2796 ruling): it used to coalesce
+  // to 0 BEFORE the finite check and silently price a dividend-free underlying.
+  ensureFiniteWhenPresent(options.dividendYield, 'dividendYield', functionName);
+  const q = options.dividendYield ?? 0;
+  ensureFiniteWhenPresent(options.steps, 'steps', functionName);
+  const steps = options.steps ?? 200;
+  // Safe integer AND a work cap (2026-08-23 review, P0): see MAX_LATTICE_STEPS.
+  if (!Number.isSafeInteger(steps) || steps < 1 || steps > MAX_LATTICE_STEPS) {
+    throw new InputError(
+      `${functionName}: steps must be an integer in [1, ${MAX_LATTICE_STEPS.toLocaleString('en-US')}] — rollback visits steps²/2 nodes (~3×10^8 combine calls ≈ 8 s at the cap, measured ~24 ns/node) and CRR error is O(1/steps), long converged by then. Received ${steps}.\n  e.g. equityLattice({ spot: 100, riskFreeRate: 0.04, volatility: 0.2, horizonYears: 1, steps: 500 })`,
+      {
+        code: ErrorCode.InputOutOfRange,
+        context: { steps, max: MAX_LATTICE_STEPS },
+      },
+    );
+  }
+  if (
+    options.variant !== undefined &&
+    options.variant !== 'crr' &&
+    options.variant !== 'jarrow-rudd'
+  ) {
+    throw new InputError(
+      `${functionName}: variant must be 'crr' | 'jarrow-rudd' when provided. Received ${options.variant === null ? 'null' : JSON.stringify(options.variant)}.`,
+      { code: ErrorCode.InputInvalidEnum, context: { field: 'variant' } },
+    );
+  }
+  const variant = options.variant ?? 'crr';
+  const timeStepYears = options.horizonYears / steps;
+  const drift = options.riskFreeRate - q;
+  const sigSqrtDt = options.volatility * Math.sqrt(timeStepYears);
+
+  let u: number;
+  let d: number;
+  let p: number;
+  if (variant === 'crr') {
+    u = Math.exp(sigSqrtDt);
+    d = 1 / u;
+    p = (Math.exp(drift * timeStepYears) - d) / (u - d);
+  } else if (variant === 'jarrow-rudd') {
+    // Equal-probability tree: p = 1/2, drift baked into u/d.
+    const nu = (drift - 0.5 * options.volatility * options.volatility) * timeStepYears;
+    u = Math.exp(nu + sigSqrtDt);
+    d = Math.exp(nu - sigSqrtDt);
+    p = 0.5;
+  } else {
+    throw new InputError(
+      `${functionName}: variant must be 'crr' or 'jarrow-rudd', got "${String(variant)}".`,
+      {
+        code: ErrorCode.InputInvalidEnum,
+        context: { variant },
+      },
+    );
+  }
+  // The CRR up-probability leaves [0, 1] when the per-step drift outruns the diffusion
+  // (|(rate−q)|·√dt ≥ volatility), which makes the "probabilities" — and any rolled-back value —
+  // meaningless. Fail loudly with an actionable fix rather than emitting a nonsense price.
+  if (!(p >= 0 && p <= 1)) {
+    throw new InputError(
+      `${functionName}: risk-neutral up-probability ${p} is outside [0, 1] — the ${variant} tree is unstable at timeStepYears=${timeStepYears}. Increase steps (smaller timeStepYears) or reduce the horizonYears/rate so that |(rate−dividendYield)|·√timeStepYears < volatility.`,
+      {
+        code: ErrorCode.InputOutOfRange,
+        context: {
+          p,
+          timeStepYears,
+          riskFreeRate: options.riskFreeRate,
+          dividendYield: q,
+          volatility: options.volatility,
+          variant,
+        },
+      },
+    );
+  }
+  const discount = Math.exp(-options.riskFreeRate * timeStepYears);
+  const rawSpotAt = (i: number, j: number): number =>
+    options.spot * Math.pow(u, j) * Math.pow(d, i - j);
+  const spotAt = (stepIndex: number, upMoveCount: number): number => {
+    if (
+      !Number.isSafeInteger(stepIndex) ||
+      !Number.isSafeInteger(upMoveCount) ||
+      stepIndex < 0 ||
+      stepIndex > steps ||
+      upMoveCount < 0 ||
+      upMoveCount > stepIndex
+    ) {
+      throw new InputError(
+        `equityLattice.spotAt: expected integer node coordinates with 0 ≤ upMoveCount ≤ stepIndex ≤ ${steps}; got stepIndex ${stepIndex}, upMoveCount ${upMoveCount}.`,
+        {
+          code: ErrorCode.InputOutOfRange,
+          context: { stepIndex, upMoveCount, steps },
+        },
+      );
+    }
+    return rawSpotAt(stepIndex, upMoveCount);
+  };
+
+  const rollback = (
+    terminal: (spot: number) => number,
+    combine: (node: LatticeNode) => number,
+  ): number => {
+    let values = new Array<number>(steps + 1);
+    // Internal coordinates are already proven by these loop bounds; bypass the public boundary
+    // check in this O(steps²) hot loop.
+    for (let j = 0; j <= steps; j++) values[j] = terminal(rawSpotAt(steps, j));
+    for (let i = steps - 1; i >= 0; i--) {
+      const next = new Array<number>(i + 1);
+      const t = i * timeStepYears;
+      for (let j = 0; j <= i; j++) {
+        next[j] = combine({
+          stepIndex: i,
+          upMoveCount: j,
+          spot: rawSpotAt(i, j),
+          timeToExpiryYears: t,
+          up: values[j + 1]!,
+          down: values[j]!,
+          upProbability: p,
+          discount,
+          timeStepYears,
+        });
+      }
+      values = next;
+    }
+    return values[0]!;
+  };
+
+  return { steps, timeStepYears, upProbability: p, spotAt, rollback };
+}

package/modules/options/src/exercise.ts

@@ -0,0 +1,422 @@
+/**
+ * American exercise analytics (spec: `docs/specs/american-exercise.md`, roadmap Tier 2). Two questions
+ * every American-option holder faces — "how much of this is the right to exercise early?" and "at what
+ * price should I exercise?" — answered in one call: the early-exercise **premium** (American value minus
+ * the European value it would have without early exercise), the exercise **boundary** `S*(τ)` recovered
+ * over the option's remaining life, and a plain **exercise-now** verdict.
+ *
+ * Composition, not a new model: the American value is `bawPrice` (Barone–Adesi–Whaley), chosen because
+ * it returns *exactly* the intrinsic value inside the exercise region — so the premium is `0` iff the
+ * option should be exercised now iff the spot is past the recovered boundary, all consistent.
+ */
+
+import {
+  ensureFiniteWhenPresent,
+  CONVENTIONS_VERSION,
+  type Diagnostics,
+  type DividendModel,
+  ErrorCode,
+  InputError,
+  type OptionContract,
+  type QuantWarning,
+  UnsupportedError,
+  ensureFinite,
+  ensureKnownKeys,
+  ensurePositive,
+  requireArgumentObject,
+  resolveValuationAsOf,
+  warning,
+  WarningCode,
+} from '@totalfinance/core';
+import { blackScholesPrice } from './bsm.js';
+import { hasDiscreteDividends } from './dividends.js';
+import { bawPrice } from './engines/american-approx.js';
+import { requireOptionalArgObject } from './facade-util.js';
+import { vanillaIntrinsicUnchecked } from './payoff-kernel.js';
+import { contractTimeToExpiryYears } from './time.js';
+import type { OptionMarket } from './types.js';
+
+/** Options for {@link americanExercise}. */
+export interface AmericanExerciseOptions {
+  /** Number of maturities in the boundary curve (from τ down to τ/N); default 24. `0` skips the curve. */
+  boundaryPoints?: number;
+}
+
+/** Law 12 allowlist for {@link AmericanExerciseOptions}. */
+const AMERICAN_EXERCISE_KEYS = ['boundaryPoints'] as const;
+const AMERICAN_EXERCISE_REQUEST_KEYS = ['contract', 'market', 'options'] as const;
+
+/** One point on the exercise-boundary curve. */
+export interface BoundaryPoint {
+  /** Time to expiry (years) at this point. */
+  yearsToExpiry: number;
+  /** The critical spot `S*` at that maturity. */
+  criticalSpot: number;
+}
+
+/** The American exercise analysis. */
+export interface AmericanExerciseResult {
+  /**
+   * Which leg was analysed — `'call'` or `'put'`.
+   *
+   * Named `optionType` because that is what it holds: in TotalFinance `style` is the EXERCISE style
+   * (`'european' | 'american'`) everywhere else, and every one of these results is American by
+   * construction, so a field called `style` reading `'put'` was a straight collision of two
+   * vocabularies (pre-1.0 clean break, defect-fix wave, review-1).
+   */
+  optionType: 'call' | 'put';
+  spot: number;
+  /** American value (Barone–Adesi–Whaley). */
+  american: number;
+  /** European value (BSM) — the value stripped of the early-exercise right. */
+  european: number;
+  /** `american − european ≥ 0` — the dollars the early-exercise right adds. */
+  earlyExercisePremium: number;
+  /** `premium / american`. */
+  premiumFractionOfValue: number;
+  intrinsic: number;
+  /** `american − intrinsic ≥ 0`. */
+  timeValue: number;
+  /** `false` for a non-dividend call (early exercise never optimal). */
+  earlyExerciseCanBeOptimal: boolean;
+  /** `S*(τ)` at the current maturity; `null` when early exercise is never optimal. */
+  criticalSpot: number | null;
+  /** The American value has collapsed to intrinsic — no time value left to give up. */
+  shouldExerciseNow: boolean;
+  /** Signed fraction of spot to the boundary (put: `(S−S*)/S`, call: `(S*−S)/S`); `null` if no boundary. */
+  spotToBoundary: number | null;
+  /** The `S*(τ)` curve over the remaining life (empty when never optimal). */
+  boundary: BoundaryPoint[];
+  /** Prose an agent relays. */
+  rationale: string;
+  assumptions: {
+    conventionsVersion: string;
+    valueEngine: 'barone-adesi-whaley';
+    dividendModel: DividendModel;
+    timeToExpiryYears: number;
+  };
+  diagnostics: Diagnostics;
+}
+
+/** One cohesive request for American exercise analysis. */
+export interface AmericanExerciseInput {
+  contract: OptionContract;
+  market: OptionMarket;
+  options?: AmericanExerciseOptions;
+}
+
+const pct = (x: number): string => `${(x * 100).toFixed(1)}%`;
+const money = (x: number): string => x.toFixed(2);
+
+/**
+ * Recover the American exercise boundary `S*(τ)` from `bawPrice` by bisecting the edge of the region
+ * where the American value equals intrinsic. Returns `null` when early exercise is never optimal (a
+ * non-dividend call, or no bracketable boundary). Put: exercise region is low spot; call: high spot.
+ */
+function criticalSpot(input: {
+  type: 'call' | 'put';
+  strike: number;
+  timeToExpiryYears: number;
+  riskFreeRate: number;
+  dividendYield: number;
+  volatility: number;
+}): number | null {
+  const {
+    type,
+    strike: K,
+    timeToExpiryYears: tau,
+    riskFreeRate: r,
+    dividendYield: q,
+    volatility: sigma,
+  } = input;
+  if (type === 'call' && r - q >= r) return null; // q ≤ 0 — a call is never exercised early
+  const tolerance = 1e-9 * K;
+  const intrinsic = (S: number): number =>
+    vanillaIntrinsicUnchecked({ type, underlyingPrice: S, strike: K });
+  const inExercise = (S: number): boolean =>
+    bawPrice({
+      type,
+      spot: S,
+      strike: K,
+      timeToExpiryYears: tau,
+      riskFreeRate: r,
+      dividendYield: q,
+      volatility: sigma,
+    }) -
+      intrinsic(S) <=
+    tolerance;
+
+  let lo: number; // in the CONTINUATION region
+  let hi: number; // in the EXERCISE region
+  if (type === 'put') {
+    // Exercise region is low spot: deep-ITM exercises, at-the-strike continues.
+    if (!inExercise(1e-8 * K)) return null; // never optimal (e.g. r ≤ 0)
+    lo = K;
+    hi = 1e-8 * K;
+    if (inExercise(lo)) return lo; // boundary at/above the strike (τ→0) — clamp to K
+  } else {
+    // Exercise region is high spot: find an upper bracket that exercises.
+    lo = K;
+    hi = K * 4;
+    let expansions = 0;
+    while (!inExercise(hi) && expansions < 40) {
+      hi *= 2;
+      expansions++;
+    }
+    if (!inExercise(hi)) return null; // no bracketable boundary
+  }
+
+  // Bisect between the continuation endpoint `lo` and the exercise endpoint `hi`.
+  for (let it = 0; it < 100; it++) {
+    const mid = 0.5 * (lo + hi);
+    if (inExercise(mid)) hi = mid;
+    else lo = mid;
+  }
+  return 0.5 * (lo + hi);
+}
+
+/**
+ * Decompose an American option into its European value plus early-exercise premium, recover the exercise
+ * boundary `S*(τ)`, and say whether to exercise now. See `docs/specs/american-exercise.md`.
+ */
+export function americanExercise(input: AmericanExerciseInput): AmericanExerciseResult {
+  requireArgumentObject('americanExercise', 'input', input);
+  ensureKnownKeys('americanExercise', 'input', input, AMERICAN_EXERCISE_REQUEST_KEYS);
+  const { contract, market, options: options = {} } = input;
+  const functionName = 'americanExercise';
+  requireArgumentObject(functionName, 'contract', contract);
+  requireArgumentObject(functionName, 'market', market);
+  requireOptionalArgObject(functionName, 'options', options);
+  // Contract/market artifacts may carry provenance metadata; the closed options object remains strict.
+  ensureKnownKeys(functionName, 'options', options, AMERICAN_EXERCISE_KEYS);
+  const boundaryPoints = (options as Record<string, unknown>)['boundaryPoints'];
+  if (
+    boundaryPoints !== undefined &&
+    (typeof boundaryPoints !== 'number' || !Number.isFinite(boundaryPoints))
+  ) {
+    throw new InputError(
+      `${functionName}: boundaryPoints must be a finite number when provided. Received ${boundaryPoints === null ? 'null' : typeof boundaryPoints}.`,
+      { code: ErrorCode.InputWrongType, context: { field: 'boundaryPoints' } },
+    );
+  }
+
+  if (typeof market.spot !== 'number') {
+    throw new InputError(`${functionName}: market.spot is required.`, {
+      code: ErrorCode.InputMissingField,
+      context: { field: 'spot' },
+    });
+  }
+  ensurePositive(market.spot, 'spot', functionName, ErrorCode.InputNegativeSpot);
+  ensurePositive(contract.strike, 'strike', functionName, ErrorCode.InputNegativeStrike);
+  if (typeof market.riskFreeRate !== 'number') {
+    throw new InputError(`${functionName}: market.riskFreeRate (a number) is required.`, {
+      code: ErrorCode.InputMissingField,
+      context: { field: 'riskFreeRate' },
+    });
+  }
+  ensureFinite(market.riskFreeRate, 'riskFreeRate', functionName);
+  if (typeof market.volatility !== 'number') {
+    throw new InputError(`${functionName}: market.volatility is required.`, {
+      code: ErrorCode.InputMissingField,
+      context: { field: 'volatility' },
+    });
+  }
+  ensurePositive(market.volatility, 'volatility', functionName);
+  // Null is a wrong-typed value, not omission (the 350c2796 ruling): it used to coalesce
+  // to 0 BEFORE the finite check and silently price a dividend-free underlying.
+  ensureFiniteWhenPresent(market.dividendYield, 'dividendYield', functionName);
+  const q = market.dividendYield ?? 0;
+
+  const asOfMs = resolveValuationAsOf(market.asOf, functionName);
+  ensureFinite(asOfMs, 'asOf', functionName);
+  const tau = contractTimeToExpiryYears(asOfMs, contract, functionName);
+  if (tau <= 0) {
+    throw new UnsupportedError(
+      `${functionName}: contract expiry ${contract.expiry} is not after asOf.`,
+      {
+        code: ErrorCode.InputNegativeTime,
+        context: { asOf: market.asOf, expiry: contract.expiry, tau },
+      },
+    );
+  }
+
+  const type = contract.type;
+  const S = market.spot;
+  const K = contract.strike;
+  const r = market.riskFreeRate;
+  const sigma = market.volatility;
+
+  const american = bawPrice({
+    type,
+    spot: S,
+    strike: K,
+    timeToExpiryYears: tau,
+    riskFreeRate: r,
+    dividendYield: q,
+    volatility: sigma,
+  });
+  const european = blackScholesPrice({
+    type,
+    spot: S,
+    strike: K,
+    timeToExpiryYears: tau,
+    riskFreeRate: r,
+    dividendYield: q,
+    volatility: sigma,
+  });
+  const intrinsic = vanillaIntrinsicUnchecked({ type, underlyingPrice: S, strike: K });
+  const earlyExercisePremium = Math.max(0, american - european);
+  const premiumFractionOfValue = american > 0 ? earlyExercisePremium / american : 0;
+  const timeValue = Math.max(0, american - intrinsic);
+  const shouldExerciseNow = intrinsic > 0 && american - intrinsic <= 1e-8 * Math.max(1, S);
+
+  const critical = criticalSpot({
+    type,
+    strike: K,
+    timeToExpiryYears: tau,
+    riskFreeRate: r,
+    dividendYield: q,
+    volatility: sigma,
+  });
+  const earlyExerciseCanBeOptimal = critical !== null;
+  const spotToBoundary =
+    critical === null ? null : type === 'put' ? (S - critical) / S : (critical - S) / S;
+
+  // Boundary curve over the remaining life (from τ down to τ/N), skipping unbracketable maturities.
+  const boundary: BoundaryPoint[] = [];
+  const nPoints = options.boundaryPoints ?? 24;
+  // Safe integer AND a work cap (2026-08-23 review, P0 "unbounded work"): `Number.isInteger(1e308)`
+  // is `true`, so the old check admitted a boundary resolution the loop below could never finish —
+  // every point is a full criticalSpot root-solve (bisection over Black–Scholes prices, ~tens of µs),
+  // so 10,000 points is already a fraction of a second to seconds, and no plotted exercise boundary
+  // resolves more than a few hundred.
+  if (!(Number.isSafeInteger(nPoints) && nPoints >= 0 && nPoints <= 10_000)) {
+    throw new InputError(
+      `${functionName}: boundaryPoints must be an integer in [0, 10,000] — each point runs a criticalSpot root-solve (~tens of µs), so the cap is already seconds of boundary work, and a plotted boundary needs only a few hundred points. Received ${nPoints}.\n  e.g. { boundaryPoints: 48 }`,
+      {
+        code: ErrorCode.InputOutOfRange,
+        context: { boundaryPoints: nPoints, max: 10_000 },
+      },
+    );
+  }
+  if (earlyExerciseCanBeOptimal && nPoints > 0) {
+    for (let i = 0; i < nPoints; i++) {
+      const t = (tau * (nPoints - i)) / nPoints; // τ, τ·(N−1)/N, … , τ/N
+      const cs = criticalSpot({
+        type,
+        strike: K,
+        timeToExpiryYears: t,
+        riskFreeRate: r,
+        dividendYield: q,
+        volatility: sigma,
+      });
+      if (cs !== null) boundary.push({ yearsToExpiry: t, criticalSpot: cs });
+    }
+  }
+
+  const warnings: QuantWarning[] = [];
+  let dividendModel: DividendModel;
+  if (hasDiscreteDividends(market)) {
+    dividendModel = 'discreteSchedule';
+    warnings.push(
+      warning(
+        WarningCode.OptionsExerciseDiscreteDividends,
+        `${functionName}: the contract has discrete dividends, but the exercise analysis uses the continuous-yield closed form. Call early-exercise is driven by discrete dividends (right before an ex-date) — use a binomial lattice for the exact boundary there.`,
+        'warn',
+      ),
+    );
+  } else {
+    dividendModel = q === 0 ? 'none' : 'continuousYield';
+  }
+
+  const rationale = composeRationale({
+    type,
+    S,
+    K,
+    american,
+    european,
+    premium: earlyExercisePremium,
+    premiumFractionOfValue,
+    intrinsic,
+    critical,
+    shouldExerciseNow,
+    earlyExerciseCanBeOptimal,
+    spotToBoundary,
+  });
+
+  return {
+    optionType: type,
+    spot: S,
+    american,
+    european,
+    earlyExercisePremium,
+    premiumFractionOfValue,
+    intrinsic,
+    timeValue,
+    earlyExerciseCanBeOptimal,
+    criticalSpot: critical,
+    shouldExerciseNow,
+    spotToBoundary,
+    boundary,
+    rationale,
+    assumptions: {
+      conventionsVersion: CONVENTIONS_VERSION,
+      valueEngine: 'barone-adesi-whaley',
+      dividendModel,
+      timeToExpiryYears: tau,
+    },
+    diagnostics: {
+      engine: 'american-exercise',
+      method: 'baw + boundary-bisection',
+      converged: true,
+      warnings,
+    },
+  };
+}
+
+interface RationaleParts {
+  type: 'call' | 'put';
+  S: number;
+  K: number;
+  american: number;
+  european: number;
+  premium: number;
+  premiumFractionOfValue: number;
+  intrinsic: number;
+  critical: number | null;
+  shouldExerciseNow: boolean;
+  earlyExerciseCanBeOptimal: boolean;
+  spotToBoundary: number | null;
+}
+
+/** Compose the prose rationale from the exercise analysis. */
+function composeRationale(p: RationaleParts): string {
+  const name = `American ${p.type}`;
+  if (!p.earlyExerciseCanBeOptimal) {
+    return `Never exercise early: with no dividend an ${name} equals its European value (${money(
+      p.american,
+    )}), so the early-exercise right is worthless — always sell rather than exercise.`;
+  }
+  if (p.shouldExerciseNow) {
+    return `Exercise now: the ${name} is worth exactly its intrinsic value (${money(
+      p.intrinsic,
+    )}) — the spot is past the exercise boundary (${money(
+      p.critical!,
+    )}), so there is no time value left to give up by exercising.`;
+  }
+  const move =
+    p.type === 'put'
+      ? `if the stock falls to ${money(p.critical!)} (currently ${money(p.S)}, ${pct(
+          p.spotToBoundary!,
+        )} above)`
+      : `if the stock rises to ${money(p.critical!)} (currently ${money(p.S)}, ${pct(
+          p.spotToBoundary!,
+        )} below)`;
+  return `Hold, don't exercise: the ${name} (${money(
+    p.american,
+  )}) exceeds its European value (${money(p.european)}) by ${money(
+    p.premium,
+  )} — the early-exercise right is ${pct(
+    p.premiumFractionOfValue,
+  )} of the value and would be thrown away by exercising now. Exercise ${move}.`;
+}