@insiderfinance/totalfinance 0.1.0

package/modules/options/src/engines/fdm.ts

@@ -0,0 +1,302 @@
+/**
+ * Crank–Nicolson finite-difference engine (spec §9.3).
+ *
+ * Solves the Black–Scholes PDE on a uniform price grid with the Crank–Nicolson (θ = ½) scheme. The
+ * American early-exercise constraint is imposed as a linear complementarity problem solved by
+ * Projected SOR (PSOR) at each time step. The price at the requested spot is linearly interpolated
+ * off the grid.
+ *
+ * The grid is sized from the DISTRIBUTION, not from a fixed multiple of the spot:
+ *
+ *   • `Smax = max(4·max(S, K), S·e^{(r−q)T + 4σ√T})` — a σ√T-blind truncation at 4·max(S, K) chops
+ *     real probability mass off a long-dated/high-vol contract (+45% at T=10, σ=1.5) and says nothing;
+ *   • the grid is refined until at least {@link NEAR_STRIKE_NODES} nodes span `K ± 2σ√T·S`, so the
+ *     payoff kink stays resolved as `Smax` grows (a σ√T-aware domain on a coarse grid just trades
+ *     one bias for another; the short-dated −5.5% case is exactly that);
+ *   • that refinement is capped at {@link GRID_POINT_CAP} nodes. When the cap binds, the domain is
+ *     truncated to what the budget can resolve and the result is flagged
+ *     `engine.discretization_inadequate` with `converged: false` — a uniform-in-S grid genuinely
+ *     cannot both span 4σ√T of a σ√T ≈ 4.7 distribution and resolve the strike, and saying so is the
+ *     only honest option.
+ *
+ * The upper boundary carries the carry: a call at `Smax` is worth `Smax·e^{−qτ} − K·e^{−rτ}`, and an
+ * American one at least its intrinsic `Smax − K`; the omitted `e^{−qτ}` was a dividend-blind bias of
+ * its own at long maturities.
+ */
+
+import {
+  ConvergenceError,
+  ErrorCode,
+  type OptionStyle,
+  type OptionType,
+  type QuantWarning,
+  warning,
+} from '@totalfinance/core';
+import { linearInterp } from '@totalfinance/math';
+import { vanillaIntrinsicUnchecked } from '../payoff-kernel.js';
+
+export interface FdmParameters {
+  type: OptionType;
+  style: OptionStyle;
+  spot: number;
+  strike: number;
+  timeToExpiryYears: number;
+  riskFreeRate: number;
+  dividendYield: number;
+  volatility: number;
+  gridPoints: number;
+  timeSteps: number;
+}
+
+/** Minimum number of grid nodes across the `K ± 2σ√T·S` window where the payoff kink lives. */
+export const NEAR_STRIKE_NODES = 25;
+/** Ceiling on AUTOMATIC grid refinement (an explicit larger `gridPoints` request is still honored). */
+export const GRID_POINT_CAP = 1600;
+
+/** The grid a Crank–Nicolson solve actually ran on — disclosed, never assumed by the caller. */
+export interface FdmGrid {
+  /** Upper truncation of the price domain. */
+  maximumSpot: number;
+  /** Number of price intervals (the grid has `gridPoints + 1` nodes). */
+  gridPoints: number;
+  timeSteps: number;
+  /** Uniform node spacing `maximumSpot / gridPoints`. */
+  spotStep: number;
+}
+
+/** A completed Crank–Nicolson solve: the price, the grid's own Greeks, and its honest diagnostics. */
+export interface FdmSolution {
+  value: number;
+  /** ∂V/∂S from the spatial stencil at the grid's OWN spacing (never a sub-grid bump). */
+  delta: number;
+  /** ∂²V/∂S² from the same stencil. */
+  gamma: number;
+  /** ∂V/∂t per YEAR, from the first two time levels of the solve. */
+  thetaPerYear: number;
+  /** `false` when the grid could not be refined enough for the requested regime. */
+  converged: boolean;
+  warnings: QuantWarning[];
+  grid: FdmGrid;
+}
+
+/**
+ * Thomas algorithm for the Crank–Nicolson step on interior nodes `1 … size−1`:
+ *
+ *   −a[j]·V[j−1] + (1 − b[j])·V[j] − c[j]·V[j+1] = rhs[j]
+ *
+ * with `out[0]` / `out[size]` already holding the Dirichlet boundary values. The interior solution is
+ * written back into `out`. Exact (no iteration): a European price is never a function of a residual
+ * tolerance.
+ */
+function solveTridiagonal(input: {
+  lower: number[];
+  diagonal: number[];
+  upper: number[];
+  rhs: number[];
+  out: number[];
+  size: number;
+}): void {
+  const { lower: a, diagonal: b, upper: c, rhs, out, size: M } = input;
+  const n = M - 1; // interior count
+  if (n < 1) return;
+  const cPrime = new Array<number>(M).fill(0);
+  const dPrime = new Array<number>(M).fill(0);
+  const rhsAt = (j: number): number =>
+    rhs[j]! + (j === 1 ? a[1]! * out[0]! : 0) + (j === M - 1 ? c[M - 1]! * out[M]! : 0);
+  let denominator = 1 - b[1]!;
+  cPrime[1] = -c[1]! / denominator;
+  dPrime[1] = rhsAt(1) / denominator;
+  for (let j = 2; j <= M - 1; j++) {
+    denominator = 1 - b[j]! - -a[j]! * cPrime[j - 1]!;
+    cPrime[j] = -c[j]! / denominator;
+    dPrime[j] = (rhsAt(j) - -a[j]! * dPrime[j - 1]!) / denominator;
+  }
+  out[M - 1] = dPrime[M - 1]!;
+  for (let j = M - 2; j >= 1; j--) out[j] = dPrime[j]! - cPrime[j]! * out[j + 1]!;
+}
+
+/** Resolve the price domain and node count for one contract (see the module docstring). */
+function resolveGrid(p: FdmParameters): {
+  grid: FdmGrid;
+  adequate: boolean;
+  requiredPoints: number;
+  idealMaximumSpot: number;
+} {
+  const requested = Math.max(40, Math.floor(p.gridPoints));
+  const timeSteps = Math.max(40, Math.floor(p.timeSteps));
+  const anchor = Math.max(p.spot, p.strike);
+  const volatilityRootTime = p.volatility * Math.sqrt(p.timeToExpiryYears);
+  // Four standard deviations of log-spot beyond the forward, floored at the historical 4·max(S, K).
+  const idealMaximumSpot = Math.max(
+    4 * anchor,
+    p.spot *
+      Math.exp((p.riskFreeRate - p.dividendYield) * p.timeToExpiryYears + 4 * volatilityRootTime),
+  );
+  // Resolution the payoff kink needs: NEAR_STRIKE_NODES nodes across K ± 2σ√T·S.
+  const nearStrikeStep = (4 * volatilityRootTime * p.spot) / NEAR_STRIKE_NODES;
+  const requiredPoints = Math.ceil(idealMaximumSpot / nearStrikeStep);
+  const gridPoints = Math.max(requested, Math.min(requiredPoints, GRID_POINT_CAP));
+  const affordableMaximumSpot = gridPoints * nearStrikeStep;
+  // Never truncate tighter than the historical 4·max(S, K) domain, whatever the resolution rule asks.
+  const maximumSpot = Math.max(4 * anchor, Math.min(idealMaximumSpot, affordableMaximumSpot));
+  const spotStep = maximumSpot / gridPoints;
+  const adequate =
+    maximumSpot >= idealMaximumSpot * (1 - 1e-12) && spotStep <= nearStrikeStep * (1 + 1e-12);
+  return {
+    grid: { maximumSpot, gridPoints, timeSteps, spotStep },
+    adequate,
+    requiredPoints,
+    idealMaximumSpot,
+  };
+}
+
+/**
+ * Crank–Nicolson solve returning the price, the grid's native first-order Greeks, and diagnostics.
+ *
+ * `delta`/`gamma` come from the three-point stencil around the grid node nearest the spot, at the
+ * grid's OWN spacing, Taylor-shifted to the spot; `theta` from the first two time levels. A
+ * bump-and-reprice Greek at a sub-`dS` step differences the linear interpolation between two fixed
+ * nodes — which is exactly zero curvature, or a sawtooth once the bump straddles a node.
+ */
+export function crankNicolsonSolve(p: FdmParameters): FdmSolution {
+  const { grid, adequate, requiredPoints, idealMaximumSpot } = resolveGrid(p);
+  const M = grid.gridPoints;
+  const N = grid.timeSteps;
+  const Smax = grid.maximumSpot;
+  const dS = grid.spotStep;
+  const timeStepYears = p.timeToExpiryYears / N;
+  const r = p.riskFreeRate;
+  const q = p.dividendYield;
+  const sig2 = p.volatility * p.volatility;
+
+  const payoff = (S: number): number =>
+    vanillaIntrinsicUnchecked({ type: p.type, underlyingPrice: S, strike: p.strike });
+
+  let V = new Array<number>(M + 1);
+  for (let j = 0; j <= M; j++) V[j] = payoff(j * dS);
+
+  const a = new Array<number>(M + 1).fill(0);
+  const b = new Array<number>(M + 1).fill(0);
+  const c = new Array<number>(M + 1).fill(0);
+  for (let j = 1; j < M; j++) {
+    a[j] = 0.25 * timeStepYears * (sig2 * j * j - (r - q) * j);
+    b[j] = -0.5 * timeStepYears * (sig2 * j * j + r);
+    c[j] = 0.25 * timeStepYears * (sig2 * j * j + (r - q) * j);
+  }
+
+  // Relaxation factor for the American LCP sweep. The classical fixed 1.4 converges at a rate that
+  // degrades like 1 − O(1/M), so a refined grid (M in the hundreds, let alone the 1600-node cap)
+  // cannot reach the residual floor inside any sane iteration budget; the optimal-SOR value for a
+  // tridiagonal system, capped at 1.9 for the projection's stability, keeps the sweep count flat.
+  const omega = Math.min(1.9, 2 / (1 + Math.sin(Math.PI / M)));
+  // Residual floors scale with the value scale — an absolute 1e-9 is below double precision once the
+  // grid (and therefore the call's upper boundary) reaches 1e5.
+  const valueScale = Math.max(1, p.strike, p.spot, Smax * Math.exp(-q * p.timeToExpiryYears));
+  const residualFloor = 1e-9 * valueScale;
+  const residualFailure = 1e-6 * valueScale;
+  // The level one time step after valuation (t = dt), kept for the native theta.
+  let levelAfterValuation: number[] | undefined;
+  for (let n = N - 1; n >= 0; n--) {
+    if (n === 0) levelAfterValuation = V;
+    const tau = p.timeToExpiryYears - n * timeStepYears;
+    const discountedStrike = p.strike * Math.exp(-r * tau);
+    // A call at Smax is (almost) certainly exercised, so it is worth the FORWARD of the truncation
+    // level less the discounted strike — Smax·e^{−qτ} − K·e^{−rτ}, not Smax − K·e^{−rτ}.
+    const europeanUpper =
+      p.type === 'call' ? Math.max(0, Smax * Math.exp(-q * tau) - discountedStrike) : 0;
+    // At S = 0 a call is worthless; a European put is worth the discounted strike, and an American
+    // put its immediate exercise value K (exercising at S = 0 is optimal and always available).
+    const europeanLower = p.type === 'call' ? 0 : discountedStrike;
+    const lower =
+      p.style === 'american' && p.type === 'put'
+        ? Math.max(europeanLower, p.strike)
+        : europeanLower;
+    const upper =
+      p.style === 'american' && p.type === 'call'
+        ? Math.max(europeanUpper, Smax - p.strike)
+        : europeanUpper;
+
+    const rhs = new Array<number>(M + 1).fill(0);
+    for (let j = 1; j < M; j++)
+      rhs[j] = a[j]! * V[j - 1]! + (1 + b[j]!) * V[j]! + c[j]! * V[j + 1]!;
+
+    const Vnew = V.slice();
+    Vnew[0] = lower;
+    Vnew[M] = upper;
+    if (p.style === 'european') {
+      // No obstacle ⇒ a plain tridiagonal system: the Thomas algorithm solves it EXACTLY in O(M),
+      // so a European price never depends on an iteration budget at all.
+      solveTridiagonal({ lower: a, diagonal: b, upper: c, rhs, out: Vnew, size: M });
+    } else {
+      const maximumIterations = 10000;
+      let residual = Infinity;
+      for (let iter = 0; iter < maximumIterations; iter++) {
+        let err = 0;
+        for (let j = 1; j < M; j++) {
+          const gaussSeidel = (rhs[j]! + a[j]! * Vnew[j - 1]! + c[j]! * Vnew[j + 1]!) / (1 - b[j]!);
+          let vj = Vnew[j]! + omega * (gaussSeidel - Vnew[j]!);
+          vj = Math.max(vj, payoff(j * dS));
+          const difference = vj - Vnew[j]!;
+          err += difference * difference;
+          Vnew[j] = vj;
+        }
+        residual = Math.sqrt(err);
+        if (residual < residualFloor) break;
+      }
+      // Honest non-convergence (design law #4): never return a guessed grid as if it converged. A
+      // residual still above a loose floor after `maximumIterations` PSOR sweeps means the solve genuinely failed.
+      if (residual > residualFailure) {
+        throw new ConvergenceError(
+          `crankNicolson: PSOR did not converge at time step ${n} (residual ${residual.toExponential(2)} after ${maximumIterations} iterations).`,
+          {
+            code: ErrorCode.SolverNoConvergence,
+            context: { step: n, residual, maximumIterations, gridPoints: M },
+          },
+        );
+      }
+    }
+    V = Vnew;
+  }
+
+  const xs = Array.from({ length: M + 1 }, (_, j) => j * dS);
+  const value = linearInterp(xs, V, p.spot);
+
+  // ── native spot Greeks: the grid's own stencil, centred on the node nearest the spot ──
+  const centre = Math.min(M - 1, Math.max(1, Math.round(p.spot / dS)));
+  const centredDelta = (V[centre + 1]! - V[centre - 1]!) / (2 * dS);
+  const gamma = (V[centre + 1]! - 2 * V[centre]! + V[centre - 1]!) / (dS * dS);
+  const offset = p.spot - centre * dS;
+  const delta = centredDelta + gamma * offset;
+  const previousLevel = levelAfterValuation ?? V;
+  const thetaPerYear = (linearInterp(xs, previousLevel, p.spot) - value) / timeStepYears;
+
+  const warnings: QuantWarning[] = adequate
+    ? []
+    : [
+        warning(
+          ErrorCode.EngineDiscretizationInadequate,
+          `crankNicolson: this regime needs ~${requiredPoints} grid points to span ` +
+            `S·e^{(r−q)T + 4σ√T} = ${idealMaximumSpot.toExponential(2)} while keeping ${NEAR_STRIKE_NODES} nodes ` +
+            `across K ± 2σ√T·S; the grid was capped at ${M} points over [0, ${Smax.toExponential(2)}], so the ` +
+            `value is truncation-biased (low for a call) and is reported unconverged. Raise gridPoints, or price ` +
+            `this regime with a lattice — engines.binomial({ variant: 'leisen-reimer', steps: 1001 }) — whose ` +
+            `multiplicative grid spans σ√T natively.`,
+          'warn',
+          {
+            requiredGridPoints: requiredPoints,
+            gridPoints: M,
+            maximumSpot: Smax,
+            idealMaximumSpot,
+            spotStep: dS,
+            volatilityRootTime: p.volatility * Math.sqrt(p.timeToExpiryYears),
+          },
+        ),
+      ];
+
+  return { value, delta, gamma, thetaPerYear, converged: adequate, warnings, grid };
+}
+
+/** Crank–Nicolson price at the requested spot. */
+export function crankNicolsonPrice(p: FdmParameters): number {
+  return crankNicolsonSolve(p).value;
+}

package/modules/options/src/engines/scalar-pricing.ts

@@ -0,0 +1,27 @@
+import type { OptionStyle, OptionType } from '@totalfinance/core';
+
+/**
+ * Fully named scalar request shared by American engine adapters and closed-form approximations.
+ *
+ * This type is intentionally internal. It prevents the same spot/strike/time/rate/yield/volatility
+ * transpositions inside the engine graph that Phase 3A removes from the public surface.
+ */
+export interface ScalarAmericanPricingInput {
+  type: OptionType;
+  style: OptionStyle;
+  spot: number;
+  strike: number;
+  timeToExpiryYears: number;
+  riskFreeRate: number;
+  dividendYield: number;
+  volatility: number;
+}
+
+/** American-engine scalar callback with one cohesive, named request. */
+export type ScalarAmericanPricer = (input: ScalarAmericanPricingInput) => number;
+
+/** Closed-form approximation request; exercise style is implied to be American. */
+export type AmericanApproximationInput = Omit<ScalarAmericanPricingInput, 'style'>;
+
+/** Closed-form American approximation callback. */
+export type AmericanApproximationPricer = (input: AmericanApproximationInput) => number;

package/modules/options/src/engines/tree.ts

@@ -0,0 +1,350 @@
+/**
+ * Lattice option engines (spec §9.3): binomial (CRR, Jarrow–Rudd, Tian, Leisen–Reimer) and
+ * trinomial, with European/American exercise. These are the convergence reference for the
+ * closed-form American approximations.
+ *
+ * Discrete cash dividends are handled by the escrowed-dividend approximation (spot reduced by the
+ * present value of dividends paid before expiry) — documented and adequate for the lattice; a full
+ * ex-date tree adjustment is a later refinement.
+ *
+ * Two invariants make a lattice value trustworthy, and both are enforced here:
+ *   1. the branch probabilities are genuine probabilities — `engine.probability_out_of_range` when
+ *      the per-step drift outruns the diffusion and they leave [0, 1];
+ *   2. the first-order spot Greeks are read off the tree's OWN early nodes ({@link binomialSolve},
+ *      {@link trinomialSolve}) rather than by re-pricing at a bumped spot. A bump smaller than the
+ *      node spacing differences the lattice's sawtooth instead of the value function — that is how a
+ *      gamma of 0.377 (or exactly 0) gets produced for a true 0.0189.
+ */
+
+import { ErrorCode, InputError, type OptionStyle, type OptionType } from '@totalfinance/core';
+import { vanillaIntrinsicUnchecked } from '../payoff-kernel.js';
+
+export type BinomialVariant = 'crr' | 'jarrow-rudd' | 'tian' | 'leisen-reimer';
+
+function intrinsic(type: OptionType, S: number, K: number): number {
+  return vanillaIntrinsicUnchecked({ type, underlyingPrice: S, strike: K });
+}
+
+/**
+ * Peizer–Pratt inversion of the normal CDF used by the Leisen–Reimer tree.
+ *
+ * The result is nudged inside the OPEN interval (0, 1): the closed form saturates to exactly 0 or 1
+ * once `|z|` is large (a vanishing volatility, or a spot far from the strike), and the tree's
+ * `d = (drift − p·u)/(1 − p)` is then 0/0 → NaN — a "price" that used to reach an implied-volatility
+ * search as a successful number. At the clamp the tree collapses to `u = d = drift`, which is exactly
+ * the deterministic σ→0 limit it is approaching.
+ */
+function peizerPratt(z: number, n: number): number {
+  const a = z / (n + 1 / 3 + 0.1 / (n + 1));
+  const b = a * a * (n + 1 / 6);
+  const p = 0.5 + Math.sign(z) * 0.5 * Math.sqrt(1 - Math.exp(-b));
+  return Math.min(1 - PEIZER_PRATT_EPSILON, Math.max(PEIZER_PRATT_EPSILON, p));
+}
+
+/** How far inside (0, 1) the Peizer–Pratt probability is held (see {@link peizerPratt}). */
+const PEIZER_PRATT_EPSILON = 1e-12;
+
+interface Lattice {
+  u: number;
+  d: number;
+  p: number;
+}
+
+/** The branch probabilities of one lattice parameterization, named as the caller reads them. */
+interface ProbabilityCheckInput {
+  /** Diagnostic label of the pricer that built them (e.g. `binomialPrice(crr)`). */
+  method: string;
+  /** Every branch probability the scheme produced, by name (`p`, or `pu`/`pm`/`pd`). */
+  probabilities: Record<string, number>;
+  timeStepYears: number;
+  steps: number;
+  riskFreeRate: number;
+  dividendYield: number;
+  volatility: number;
+  /** The engine-specific escape hatch appended to the teaching message. */
+  alternative: string;
+}
+
+/**
+ * Reject a lattice whose risk-neutral branch probabilities left [0, 1].
+ *
+ * A "probability" outside [0, 1] is not a slightly-worse discretization — the rolled-back value is a
+ * signed combination with no risk-neutral meaning, and it can either explode (−2.6e51 for a European
+ * call) or look perfectly plausible (a 4.4×-low American put). Both are silent wrong numbers, so
+ * this is a hard failure carrying the actionable fix, mirroring the equity lattice's guard.
+ */
+function requireProbabilitiesInRange(input: ProbabilityCheckInput): void {
+  const {
+    method,
+    probabilities,
+    timeStepYears,
+    steps,
+    riskFreeRate,
+    dividendYield,
+    volatility,
+    alternative,
+  } = input;
+  for (const [name, value] of Object.entries(probabilities)) {
+    if (value >= 0 && value <= 1) continue;
+    throw new InputError(
+      `${method}: risk-neutral branch probability ${name}=${value} is outside [0, 1] — the tree is ` +
+        `unstable at timeStepYears=${timeStepYears} (the per-step drift |riskFreeRate − dividendYield|·timeStepYears ` +
+        `outran the diffusion volatility·√timeStepYears, so the branch weights — and every value rolled back ` +
+        `through them — carry no risk-neutral meaning). Increase steps (a smaller timeStepYears), shorten ` +
+        `timeToExpiryYears, or reduce |riskFreeRate − dividendYield| so that ` +
+        `|riskFreeRate − dividendYield|·√timeStepYears < volatility; ${alternative}`,
+      {
+        code: ErrorCode.EngineProbabilityOutOfRange,
+        context: {
+          engine: method,
+          probability: name,
+          value,
+          timeStepYears,
+          steps,
+          riskFreeRate,
+          dividendYield,
+          volatility,
+        },
+      },
+    );
+  }
+}
+
+function latticeParams(input: TreePriceParameters & { variant: BinomialVariant }): Lattice {
+  const {
+    variant,
+    spot: S,
+    strike: K,
+    timeToExpiryYears: T,
+    riskFreeRate: r,
+    dividendYield: q,
+    volatility: sigma,
+    steps,
+  } = input;
+  const timeStepYears = T / steps;
+  const drift = Math.exp((r - q) * timeStepYears);
+  const lattice = ((): Lattice => {
+    switch (variant) {
+      case 'crr': {
+        const u = Math.exp(sigma * Math.sqrt(timeStepYears));
+        const d = 1 / u;
+        return { u, d, p: (drift - d) / (u - d) };
+      }
+      case 'jarrow-rudd': {
+        const nu = r - q - 0.5 * sigma * sigma;
+        const u = Math.exp(nu * timeStepYears + sigma * Math.sqrt(timeStepYears));
+        const d = Math.exp(nu * timeStepYears - sigma * Math.sqrt(timeStepYears));
+        return { u, d, p: (drift - d) / (u - d) };
+      }
+      case 'tian': {
+        const v = Math.exp(sigma * sigma * timeStepYears);
+        const root = Math.sqrt(v * v + 2 * v - 3);
+        const u = 0.5 * drift * v * (v + 1 + root);
+        const d = 0.5 * drift * v * (v + 1 - root);
+        return { u, d, p: (drift - d) / (u - d) };
+      }
+      case 'leisen-reimer': {
+        const sqrtT = Math.sqrt(T);
+        const d1 = (Math.log(S / K) + (r - q + 0.5 * sigma * sigma) * T) / (sigma * sqrtT);
+        const d2 = d1 - sigma * sqrtT;
+        const p = peizerPratt(d2, steps);
+        const pPrime = peizerPratt(d1, steps);
+        const u = drift * (pPrime / p);
+        const d = (drift - p * u) / (1 - p);
+        return { u, d, p };
+      }
+    }
+  })();
+  // Leisen–Reimer's Peizer–Pratt inversion returns 0.5 ± 0.5·√(1 − e^{−b}) with b ≥ 0, so its `p` is
+  // structurally inside (0, 1) for every finite parameter set — it is the escape hatch the message
+  // below recommends, and a regression test pins that it never trips this guard.
+  requireProbabilitiesInRange({
+    method: `binomialPrice(${variant})`,
+    probabilities: { p: lattice.p },
+    timeStepYears,
+    steps,
+    riskFreeRate: r,
+    dividendYield: q,
+    volatility: sigma,
+    alternative:
+      variant === 'leisen-reimer'
+        ? 'the Leisen–Reimer probability is structurally in (0, 1), so a violation here means a non-finite input reached the tree.'
+        : "or switch to engines.binomial({ variant: 'leisen-reimer' }), whose Peizer–Pratt probability is in (0, 1) by construction.",
+  });
+  return lattice;
+}
+
+export interface TreePriceParameters {
+  type: OptionType;
+  style: OptionStyle;
+  spot: number;
+  strike: number;
+  timeToExpiryYears: number;
+  riskFreeRate: number;
+  dividendYield: number;
+  volatility: number;
+  steps: number;
+}
+
+/**
+ * Three adjacent nodes of an early tree layer (ascending in spot) plus the layer's calendar time —
+ * everything {@link latticeSpotGreeks} needs to read delta/gamma/theta off the tree itself.
+ */
+export interface EarlyTreeLayer {
+  /** Node spots, strictly ascending. */
+  spots: [number, number, number];
+  /** Node values, aligned with `spots`. */
+  values: [number, number, number];
+  /** Calendar time of the layer, in years from valuation (`stepIndex · timeStepYears`). */
+  timeYears: number;
+}
+
+/** A rolled-back lattice: the root value plus the early layer used for native spot Greeks. */
+export interface TreeSolution {
+  value: number;
+  /** Absent when the tree is too shallow to expose an interior layer (binomial steps < 3, trinomial < 2). */
+  early: EarlyTreeLayer | undefined;
+}
+
+/** First-order Greeks read directly off a discretization, in raw (unscaled) units. */
+export interface NativeSpotGreeks {
+  delta: number;
+  gamma: number;
+  /** ∂V/∂t per YEAR (calendar decay, so negative for a long option). */
+  thetaPerYear: number;
+}
+
+/**
+ * Delta, gamma and theta from three adjacent nodes of an early layer.
+ *
+ * The three-point formulas are the exact derivatives of the parabola through the (unequally spaced)
+ * nodes, evaluated at the middle node and then Taylor-shifted to the valuation spot — the shift is
+ * what keeps Jarrow–Rudd/Tian/Leisen–Reimer honest, since only CRR has a middle node sitting exactly
+ * on `spot`. Theta compares the layer's value AT the spot with the root value over the layer's own
+ * elapsed time, so no re-pricing at a bumped maturity is involved.
+ */
+export function latticeSpotGreeks(input: {
+  spot: number;
+  rootValue: number;
+  early: EarlyTreeLayer;
+}): NativeSpotGreeks {
+  const { spot: S, rootValue, early } = input;
+  const [x0, x1, x2] = early.spots;
+  const [v0, v1, v2] = early.values;
+  const h1 = x1 - x0;
+  const h2 = x2 - x1;
+  const firstDerivative =
+    (-h2 / (h1 * (h1 + h2))) * v0 + ((h2 - h1) / (h1 * h2)) * v1 + (h1 / (h2 * (h1 + h2))) * v2;
+  const secondDerivative = 2 * (v0 / (h1 * (h1 + h2)) - v1 / (h1 * h2) + v2 / (h2 * (h1 + h2)));
+  const offset = S - x1;
+  const delta = firstDerivative + secondDerivative * offset;
+  const gamma = secondDerivative;
+  // The layer's value AT the valuation spot (second-order Taylor from the middle node).
+  const valueAtSpot = v1 + firstDerivative * offset + 0.5 * secondDerivative * offset * offset;
+  const thetaPerYear = (valueAtSpot - rootValue) / early.timeYears;
+  return { delta, gamma, thetaPerYear };
+}
+
+/** Roll a binomial tree back to the root, capturing the step-2 layer for native Greeks. */
+export function binomialSolve(variant: BinomialVariant, p: TreePriceParameters): TreeSolution {
+  const steps = Math.max(1, Math.floor(p.steps));
+  const timeStepYears = p.timeToExpiryYears / steps;
+  const disc = Math.exp(-p.riskFreeRate * timeStepYears);
+  const { u, d, p: prob } = latticeParams({ ...p, variant, steps });
+
+  const values = new Array<number>(steps + 1);
+  for (let i = 0; i <= steps; i++) {
+    const ST = p.spot * u ** (steps - i) * d ** i;
+    values[i] = intrinsic(p.type, ST, p.strike);
+  }
+  let early: EarlyTreeLayer | undefined;
+  for (let step = steps - 1; step >= 0; step--) {
+    for (let i = 0; i <= step; i++) {
+      let cont = disc * (prob * values[i]! + (1 - prob) * values[i + 1]!);
+      if (p.style === 'american') {
+        const ST = p.spot * u ** (step - i) * d ** i;
+        cont = Math.max(cont, intrinsic(p.type, ST, p.strike));
+      }
+      values[i] = cont;
+    }
+    // The step-2 layer (three nodes at 2·timeStepYears) is the standard source of a binomial tree's
+    // own delta/gamma/theta. A 1- or 2-step tree never reaches it, and the caller falls back to bumps.
+    if (step === 2) {
+      early = {
+        spots: [p.spot * d * d, p.spot * u * d, p.spot * u * u],
+        values: [values[2]!, values[1]!, values[0]!],
+        timeYears: 2 * timeStepYears,
+      };
+    }
+  }
+  return { value: values[0]!, early };
+}
+
+/** Binomial tree price (American or European). */
+export function binomialPrice(variant: BinomialVariant, p: TreePriceParameters): number {
+  return binomialSolve(variant, p).value;
+}
+
+/** Roll a trinomial tree back to the root, capturing the step-1 layer for native Greeks. */
+export function trinomialSolve(p: TreePriceParameters): TreeSolution {
+  const steps = Math.max(1, Math.floor(p.steps));
+  const timeStepYears = p.timeToExpiryYears / steps;
+  const disc = Math.exp(-p.riskFreeRate * timeStepYears);
+  const u = Math.exp(p.volatility * Math.sqrt(2 * timeStepYears)); // down move is u^{-1}; node spots use u^j directly
+
+  const eHalf = Math.exp(((p.riskFreeRate - p.dividendYield) * timeStepYears) / 2);
+  const eSig = Math.exp(p.volatility * Math.sqrt(timeStepYears / 2));
+  const eSigInv = 1 / eSig;
+  const pu = ((eHalf - eSigInv) / (eSig - eSigInv)) ** 2;
+  const pd = ((eSig - eHalf) / (eSig - eSigInv)) ** 2;
+  const pm = 1 - pu - pd;
+  // Boyle's parameterization squares its numerators, so pu/pd stay non-negative while pm goes
+  // silently negative (pu = 1.31, pm = −0.33 at σ=1%, r=10%, T=10): all three are checked.
+  requireProbabilitiesInRange({
+    method: 'trinomialPrice',
+    probabilities: { pu, pm, pd },
+    timeStepYears,
+    steps,
+    riskFreeRate: p.riskFreeRate,
+    dividendYield: p.dividendYield,
+    volatility: p.volatility,
+    alternative:
+      "or switch to engines.binomial({ variant: 'leisen-reimer' }), whose Peizer–Pratt probability is in (0, 1) by construction.",
+  });
+
+  const size = 2 * steps + 1;
+  const values = new Array<number>(size);
+  for (let i = 0; i < size; i++) {
+    const j = steps - i; // node exponent from +steps down to -steps
+    const ST = p.spot * u ** j;
+    values[i] = intrinsic(p.type, ST, p.strike);
+  }
+  let early: EarlyTreeLayer | undefined;
+  for (let step = steps - 1; step >= 0; step--) {
+    const width = 2 * step + 1;
+    for (let i = 0; i < width; i++) {
+      let cont = disc * (pu * values[i]! + pm * values[i + 1]! + pd * values[i + 2]!);
+      if (p.style === 'american') {
+        const j = step - i;
+        const ST = p.spot * u ** j;
+        cont = Math.max(cont, intrinsic(p.type, ST, p.strike));
+      }
+      values[i] = cont;
+    }
+    // A trinomial's step-1 layer already straddles the spot (its middle node IS S·u⁰), so the native
+    // Greeks come from one time step rather than two.
+    if (step === 1) {
+      early = {
+        spots: [p.spot / u, p.spot, p.spot * u],
+        values: [values[2]!, values[1]!, values[0]!],
+        timeYears: timeStepYears,
+      };
+    }
+  }
+  return { value: values[0]!, early };
+}
+
+/** Trinomial tree price (American or European). */
+export function trinomialPrice(p: TreePriceParameters): number {
+  return trinomialSolve(p).value;
+}