@insiderfinance/totalfinance 0.1.0

package/modules/options/src/contract.ts

@@ -0,0 +1,329 @@
+/**
+ * Option contract builders (spec §9.2; rewritten valid-by-construction in alignment-spec P3.4).
+ *
+ * A builder's name is a promise: what it returns is a VALID instrument. Every meaning-changing
+ * field is required (exercise `style` is never guessed — US equity options are American, many
+ * index options European), every numeric is validated at construction, and the expiry label is
+ * resolved to its exact instant HERE, with the applied convention stamped on the contract.
+ *
+ * The lovable layer is the instrument builders: `usEquityCall`/`usEquityPut` encode the US listed
+ * convention (American exercise, 16:00 ET close for date-only expiries, 100 multiplier);
+ * `european` names the European-exercise case explicitly. The generic `callContract`/`putContract`
+ * remain for full control and REQUIRE `style`.
+ */
+
+import {
+  ErrorCode,
+  InputError,
+  type OptionContract,
+  type OptionStyle,
+  type OptionType,
+  ensureEnum,
+  ensureKnownKeys,
+  ensurePositive,
+  optionExpiryToMs,
+  parseOccSymbol,
+  requireArgumentObject,
+} from '@totalfinance/core';
+import { expiryConventionOf } from './engine-bsm.js';
+
+export interface OptionBuilderInput {
+  underlying: string;
+  strike: number;
+  /** Expiry label: `YYYY-MM-DD` (requires `convention`) or a zoned ISO datetime. */
+  expiry: string;
+  /**
+   * REQUIRED for a date-only `expiry` (D2, one expiry law): a bare date does not name its
+   * INSTANT, and the generic builders never guess one — `'us-equity-close'` options into the
+   * 16:00 ET session close explicitly. The `usEquityCall`/`usEquityPut` names carry it for you.
+   */
+  convention?: 'us-equity-close';
+  /**
+   * REQUIRED (P3.4): exercise style is meaning-changing and is never defaulted — an American put
+   * is worth more than its European twin. Use `usEquityCall`/`usEquityPut`/`european` when you
+   * want the convention encoded in the builder's name instead.
+   */
+  style: OptionStyle;
+  multiplier?: number;
+  currency?: string;
+  root?: string;
+}
+
+/** Instrument-builder input: the convention lives in the builder name, so no `style` here. */
+export type InstrumentBuilderInput = Omit<OptionBuilderInput, 'style'>;
+
+const STYLES: readonly OptionStyle[] = ['european', 'american'];
+
+const BUILDER_KEYS = [
+  'underlying',
+  'strike',
+  'expiry',
+  'style',
+  'convention',
+  'multiplier',
+  'currency',
+  'root',
+] as const;
+
+const DATE_ONLY_EXPIRY = /^\d{4}-\d{2}-\d{2}$/;
+
+function validateAndResolve(
+  functionName: string,
+  type: OptionType,
+  input: OptionBuilderInput,
+): OptionContract {
+  requireArgumentObject(functionName, 'input', input);
+  ensureKnownKeys(functionName, 'input', input, BUILDER_KEYS);
+  // `type` reaches here from user input via european({ type }) — never trusted (design law #4).
+  ensureEnum(type, ['call', 'put'] as const, 'type', functionName);
+  if (typeof input.underlying !== 'string' || input.underlying.trim() === '') {
+    throw new InputError(
+      `${functionName}: underlying must be a non-blank symbol string. Received ${
+        typeof input.underlying === 'string' ? `"${input.underlying}"` : typeof input.underlying
+      }.`,
+      { code: ErrorCode.InputWrongType, context: { function: functionName, field: 'underlying' } },
+    );
+  }
+  if (!STYLES.includes(input.style)) {
+    throw new InputError(
+      `${functionName}: style is required — one of 'european' | 'american' (never defaulted: exercise style ` +
+        `changes the value). US listed equity options are American; use usEquityCall/usEquityPut ` +
+        `or european(...) to encode the convention in the builder name. Received ${
+          input.style === undefined ? 'undefined' : `"${String(input.style)}"`
+        }.`,
+      { code: ErrorCode.InputMissingField, context: { function: functionName, field: 'style' } },
+    );
+  }
+  ensurePositive(input.strike, 'strike', functionName, ErrorCode.InputNegativeStrike);
+  if (input.multiplier !== undefined) ensurePositive(input.multiplier, 'multiplier', functionName);
+  for (const field of ['currency', 'root'] as const) {
+    const v = input[field];
+    if (v !== undefined && (typeof v !== 'string' || v.trim() === '')) {
+      throw new InputError(
+        `${functionName}: ${field} must be a non-blank string when provided (omit it for none).`,
+        { code: ErrorCode.InputWrongType, context: { function: functionName, field } },
+      );
+    }
+  }
+  // The convention field is an ENUM, never a free string (E2): 'bogus' teaches, silently
+  // ignoring it would be silent economics.
+  if (input.convention !== undefined) {
+    ensureEnum(input.convention, ['us-equity-close'] as const, 'convention', functionName);
+  }
+  // A zoned datetime IS its own instant — a convention alongside it is a contradiction, not a
+  // no-op (E2): reject rather than silently discard the caller's stated meaning.
+  if (
+    input.convention !== undefined &&
+    typeof input.expiry === 'string' &&
+    !DATE_ONLY_EXPIRY.test(input.expiry)
+  ) {
+    throw new InputError(
+      `${functionName}: convention "${input.convention}" contradicts the zoned expiry "${input.expiry}" — ` +
+        'a zoned datetime already names its exact instant; omit convention (it applies to ' +
+        'date-only labels).',
+      {
+        code: ErrorCode.InputWrongShape,
+        context: { function: functionName, expiry: input.expiry },
+      },
+    );
+  }
+  // A date-only expiry must NAME its instant (D2): the generic builders take an explicit
+  // convention; only the usEquity* names imply one. `european()` shares this same check.
+  if (
+    typeof input.expiry === 'string' &&
+    DATE_ONLY_EXPIRY.test(input.expiry) &&
+    input.convention === undefined
+  ) {
+    throw new InputError(
+      `${functionName}: a date-only expiry ("${input.expiry}") does not name its expiry INSTANT. Pass a ` +
+        `zoned datetime (e.g. "${input.expiry}T16:00:00-04:00"), or add convention: ` +
+        `'us-equity-close' to opt into the 16:00 ET close explicitly. (usEquityCall/usEquityPut ` +
+        'carry that convention in their names.)',
+      {
+        code: ErrorCode.InputMissingField,
+        context: { function: functionName, field: 'convention' },
+      },
+    );
+  }
+  // Resolve the expiry label NOW — a builder never returns a contract whose expiry cannot price.
+  // optionExpiryToMs validates real calendar dates and rejects zone-less datetimes with the fix.
+  const expiresAt = optionExpiryToMs(input.expiry);
+  if (!Number.isFinite(expiresAt)) {
+    // Belt-and-braces: a frozen contract must never carry a non-finite instant (Law 7).
+    throw new InputError(
+      `${functionName}: expiry "${input.expiry}" resolved to a non-finite instant.`,
+      {
+        code: ErrorCode.InputNotFinite,
+        context: { function: functionName, expiry: input.expiry },
+      },
+    );
+  }
+  // Artifact role (Law 2): the built contract is FROZEN — a field edited after construction
+  // would silently disagree with the resolved expiresAt; engines also cross-check the pair.
+  return Object.freeze({
+    underlying: input.underlying,
+    type,
+    style: input.style,
+    strike: input.strike,
+    expiry: input.expiry,
+    expiresAt,
+    expiryConvention: expiryConventionOf(input.expiry),
+    ...(input.multiplier !== undefined ? { multiplier: input.multiplier } : {}),
+    ...(input.currency !== undefined ? { currency: input.currency } : {}),
+    ...(input.root !== undefined ? { root: input.root } : {}),
+  });
+}
+
+/** Generic call builder — `style` REQUIRED. */
+export function callContract(input: OptionBuilderInput): OptionContract {
+  return validateAndResolve('callContract', 'call', input);
+}
+
+/** Generic put builder — `style` REQUIRED. */
+export function putContract(input: OptionBuilderInput): OptionContract {
+  return validateAndResolve('putContract', 'put', input);
+}
+
+/**
+ * US listed equity call: AMERICAN exercise, date-only expiries resolve to the 16:00 ET close
+ * (`expiryConvention: 'us-equity-close'`), multiplier defaults to the standard 100.
+ *
+ * A ZONED DATETIME expiry is accepted too and is used verbatim (`expiryConvention:
+ * 'explicit-instant'`): the builder's date-only convention is what it applies when the label does
+ * not name an instant, not a claim about labels that do. Weekly/EOM contracts that expire at an
+ * instant other than 16:00 ET — and any desk that stamps the exact settlement time — go through
+ * here, not through the generic builders (defect-fix wave, review-1).
+ */
+// The usEquity* names OWN the convention (E2): neither `style` nor `convention` is accepted —
+// a supplied value would be silently identical-or-overridden, and Law 12 forbids silent.
+const INSTRUMENT_KEYS = BUILDER_KEYS.filter((k) => k !== 'style' && k !== 'convention');
+
+/**
+ * The date-only convention these builders carry, applied ONLY to a date-only label. Stamping it on
+ * a zoned datetime made the builder contradict itself: `validateAndResolve` rejects a convention
+ * next to an explicit instant, so every zoned expiry was refused with advice ("omit convention")
+ * that a caller of `usEquityCall` had no way to follow — the field is not even accepted.
+ */
+function usEquityConvention(expiry: unknown): { convention?: 'us-equity-close' } {
+  return typeof expiry === 'string' && DATE_ONLY_EXPIRY.test(expiry)
+    ? { convention: 'us-equity-close' }
+    : {};
+}
+
+export function usEquityCall(input: InstrumentBuilderInput): OptionContract {
+  requireArgumentObject('usEquityCall', 'input', input);
+  // The convention lives in the NAME — a user-supplied `style` here would be silently
+  // overridden, so it is rejected like any other unknown key (Law 12).
+  ensureKnownKeys('usEquityCall', 'input', input, INSTRUMENT_KEYS);
+  return validateAndResolve('usEquityCall', 'call', {
+    multiplier: 100,
+    ...input,
+    ...usEquityConvention(input.expiry),
+    style: 'american',
+  });
+}
+
+/** US listed equity put — see {@link usEquityCall}. */
+export function usEquityPut(input: InstrumentBuilderInput): OptionContract {
+  requireArgumentObject('usEquityPut', 'input', input);
+  ensureKnownKeys('usEquityPut', 'input', input, INSTRUMENT_KEYS);
+  return validateAndResolve('usEquityPut', 'put', {
+    multiplier: 100,
+    ...input,
+    ...usEquityConvention(input.expiry),
+    style: 'american',
+  });
+}
+
+/** Input for {@link usEquityOption}: an OCC symbol, or the contract's data with its `type`. */
+export interface UsEquityOptionInput extends Partial<InstrumentBuilderInput> {
+  /** A compact OCC symbol (`AAPL260918C00200000`); its root, expiry, type and strike are the contract. */
+  occSymbol?: string;
+  /** `'call' | 'put'` — required unless `occSymbol` names it. */
+  type?: OptionType;
+}
+
+const US_EQUITY_OPTION_KEYS = [...INSTRUMENT_KEYS, 'occSymbol', 'type'] as const;
+
+/**
+ * US listed equity option from DATA (B7): either an OCC symbol, or `type` plus the fields
+ * `usEquityCall`/`usEquityPut` take. The two named builders remain the sugar; this is the door a
+ * chain row, a fill, or a broker symbol goes through without branching on `type` first. A field
+ * given beside `occSymbol` must agree with the symbol — a contradiction is refused, never resolved
+ * by preference.
+ */
+export function usEquityOption(input: UsEquityOptionInput): OptionContract {
+  requireArgumentObject('usEquityOption', 'input', input);
+  ensureKnownKeys('usEquityOption', 'input', input, US_EQUITY_OPTION_KEYS);
+  const { occSymbol, type, ...fields } = input;
+  if (occSymbol !== undefined) {
+    if (typeof occSymbol !== 'string' || occSymbol.trim().length === 0) {
+      throw new InputError(
+        `usEquityOption: occSymbol must be a non-empty OCC option symbol string when provided.`,
+        { code: ErrorCode.InputWrongType, context: { field: 'occSymbol' } },
+      );
+    }
+    const parsed = parseOccSymbol(occSymbol);
+    // The symbol names the ROOT (`SPXW`), not the underlying (`SPX`): `underlying` may be given
+    // beside it; `root`, `type`, `strike`, and `expiry` must agree with what the symbol spells.
+    const conflicts = (
+      [
+        ['type', type, parsed.type],
+        ['root', fields.root, parsed.root],
+        ['strike', fields.strike, parsed.strike],
+        ['expiry', fields.expiry, parsed.expiry],
+      ] as const
+    ).filter(([, given, fromSymbol]) => given !== undefined && given !== fromSymbol);
+    if (conflicts.length > 0) {
+      throw new InputError(
+        `usEquityOption: ${conflicts
+          .map(
+            ([field, given, fromSymbol]) =>
+              `${field} ${JSON.stringify(given)} contradicts occSymbol's ${JSON.stringify(fromSymbol)}`,
+          )
+          .join('; ')}. Pass the symbol alone, or the fields alone.`,
+        {
+          code: ErrorCode.InputOutOfRange,
+          context: { function: 'usEquityOption', occSymbol, conflicts: conflicts.map(([f]) => f) },
+        },
+      );
+    }
+    const { strike: _strike, expiry: _expiry, root: _root, ...rest } = fields;
+    const build = parsed.type === 'call' ? usEquityCall : usEquityPut;
+    const contract = build({
+      ...rest,
+      underlying: rest.underlying ?? parsed.root,
+      strike: parsed.strike,
+      expiry: parsed.expiry,
+      root: parsed.root,
+    });
+    return Object.freeze({ ...contract, occSymbol: occSymbol.trim().toUpperCase() });
+  }
+  if (type === undefined) {
+    throw new InputError(
+      `usEquityOption: type ('call' | 'put') is required unless occSymbol is given. ` +
+        `e.g. usEquityOption({ type: 'call', underlying: 'AAPL', strike: 200, expiry: '2026-09-18' })`,
+      { code: ErrorCode.InputMissingField, context: { function: 'usEquityOption', field: 'type' } },
+    );
+  }
+  ensureEnum(type, ['call', 'put'] as const, 'type', 'usEquityOption');
+  return (type === 'call' ? usEquityCall : usEquityPut)(fields as InstrumentBuilderInput);
+}
+
+/**
+ * European-exercise contract with the convention in the name (index-style options).
+ *
+ * A DATE-ONLY expiry must say which instant it means: pass a zoned datetime, or add
+ * `convention: 'us-equity-close'` to opt into the 16:00 ET close explicitly. The silent
+ * US-equity default belongs to `usEquityCall`/`usEquityPut`, whose NAMES carry it — European
+ * index products settle at different instants (AM auctions, European closes), so guessing here
+ * would be silent economics (Law 6).
+ */
+export function european(
+  input: InstrumentBuilderInput & { type: OptionType; convention?: 'us-equity-close' },
+): OptionContract {
+  requireArgumentObject('european', 'input', input);
+  ensureKnownKeys('european', 'input', input, [...INSTRUMENT_KEYS, 'type', 'convention']);
+  const { type, ...rest } = input;
+  return validateAndResolve('european', type, { ...rest, style: 'european' });
+}

package/modules/options/src/dividend-term-structure.ts

@@ -0,0 +1,303 @@
+/**
+ * Dividend term structures (spec: `docs/specs/dividend-term-structure.md`, roadmap Tier 2). Unifies the
+ * two ways a desk carries dividends — a **discrete cash schedule** (real ex-dates and amounts) and a
+ * **continuous yield** `q` (the one number a Black–Scholes engine wants) — into a single per-maturity
+ * term structure of the dividend-adjusted forward `F(T)`, the PV of the dividends accruing before `T`,
+ * and the **continuous-equivalent yield** `q_eff(T)` that reproduces that forward exactly.
+ *
+ * EX-DATE CONVENTION: a date-only `exDate` resolves to the US equity market OPEN (09:30
+ * America/New_York), while a date-only MATURITY resolves to the 16:00 ET option close — two different
+ * events, two different instants (see {@link parseExDateToEpoch}). A zoned datetime is taken as-is.
+ *
+ * Same escrowed-dividend model as {@link escrowedSpot} (the `0 < τᵢ < T` rule), so `q_eff(T)` is a
+ * *lossless* collapse of the schedule at each expiry: pricing with `(S, r, q_eff(T), σ)` returns exactly
+ * the escrowed-spot price, because BSM depends on `(S,r,q)` only through the forward. This is the forward
+ * direction of the relationship `parity.impliedDividendYield` inverts (recovering `q_eff` from prices).
+ */
+
+import {
+  ensureFiniteWhenPresent,
+  CONVENTIONS_VERSION,
+  type Diagnostics,
+  type DividendModel,
+  type EpochMs,
+  ErrorCode,
+  InputError,
+  type QuantWarning,
+  ensureFinite,
+  ensurePositive,
+  requireArgumentObject,
+  ensureKnownKeys,
+  resolveValuationAsOf,
+  warning,
+  WarningCode,
+} from '@totalfinance/core';
+import { timeToExDateYears, timeToExpiryYears } from './time.js';
+import type { DiscreteDividend } from './types.js';
+
+/** Input for {@link dividendTermStructure}. */
+export interface DividendTermStructureInput {
+  spot: number;
+  /** Continuously-compounded risk-free rate (decimal, e.g. `0.045`). */
+  riskFreeRate: number;
+  /** Continuous dividend yield applied alongside the discrete schedule (decimal); default `0`. */
+  dividendYield?: number;
+  /** Discrete cash dividends (ISO ex-date + per-share amount). Omitted / empty ⇒ continuous-only. */
+  dividends?: DiscreteDividend[];
+  /** Valuation date; ex-dates and maturities are measured from here (epoch ms or ISO). Required. */
+  asOf: EpochMs | string;
+  /** The expiries (ISO dates) to report the term structure at. At least one, each after `asOf`. */
+  maturities: string[];
+}
+
+/** One expiry's row of the dividend term structure. */
+export interface DividendTermStructurePoint {
+  /** The maturity (ISO), echoed. */
+  maturity: string;
+  /** Year fraction from `asOf` (ACT/365F). */
+  yearsToExpiry: number;
+  /** PV of the discrete dividends accruing strictly before this expiry. */
+  dividendPresentValue: number;
+  /** How many discrete dividends accrue strictly before this expiry. */
+  discreteCount: number;
+  /** Dividend-adjusted (escrowed) forward `F(T) = (S − PV)·e^{(r−q)T}`. */
+  forward: number;
+  /** The discrete schedule expressed as a continuous yield: `−ln(1−PV/S)/T`. */
+  discreteEquivalentYield: number;
+  /** The single continuous yield that reproduces `F(T)`: `q + discreteEquivalentYield`. */
+  impliedContinuousYield: number;
+  /** Net cost-of-carry the forward grows at: `r − impliedContinuousYield` (so `F = S·e^{carry·T}`). */
+  carry: number;
+}
+
+/** The dividend term structure across the requested expiries. */
+export interface DividendTermStructure {
+  /** One row per requested expiry, sorted ascending by tenor. */
+  points: DividendTermStructurePoint[];
+  /** PV of every *future* dividend in the schedule (all `τᵢ > 0`), independent of the maturities asked. */
+  totalDividendPresentValue: number;
+  /** The continuous yield echoed back (`0` when none supplied). */
+  continuousYield: number;
+  /** One-line, agent-relayable summary. */
+  summary: string;
+  assumptions: {
+    conventionsVersion: string;
+    spot: number;
+    riskFreeRate: number;
+    continuousYield: number;
+    dividendModel: DividendModel;
+  };
+  diagnostics: Diagnostics;
+}
+
+const pct = (x: number): string => `${(x * 100).toFixed(2)}%`;
+const money = (x: number): string => x.toFixed(2);
+
+/** A future dividend resolved to its year fraction and present value. */
+interface ResolvedDividend {
+  tau: number;
+  amount: number;
+  pv: number;
+}
+
+/**
+ * Build the dividend term structure — per-expiry forward, dividend PV, and continuous-equivalent yield —
+ * from a discrete cash schedule and/or a continuous yield. See `docs/specs/dividend-term-structure.md`.
+ */
+export function dividendTermStructure(input: DividendTermStructureInput): DividendTermStructure {
+  const functionName = 'dividendTermStructure';
+  requireArgumentObject(functionName, 'input', input);
+  // Law 12 (2026-08-23, fourth review): the input is CLOSED — an unknown key is a typo teaching,
+  // never silently ignored.
+  ensureKnownKeys(functionName, 'input', input, [
+    'spot',
+    'riskFreeRate',
+    'dividendYield',
+    'dividends',
+    'asOf',
+    'maturities',
+  ]);
+
+  ensurePositive(input.spot, 'spot', functionName, ErrorCode.InputNegativeSpot);
+  const S = input.spot;
+
+  if (typeof input.riskFreeRate !== 'number') {
+    throw new InputError(`${functionName}: rate (a number) is required.`, {
+      code: ErrorCode.InputMissingField,
+      context: { field: 'riskFreeRate' },
+    });
+  }
+  ensureFinite(input.riskFreeRate, 'riskFreeRate', functionName);
+  const r = input.riskFreeRate;
+
+  // 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.
+  // `?? []` would treat an explicit `dividends: null` as an omission — null is a stated value,
+  // and a caller who wrote it is told so (2026-08-23 fourth-review enforcement).
+  for (const field of ['dividendYield', 'dividends'] as const) {
+    if (input[field] === null) {
+      throw new InputError(
+        `${functionName}: ${field} must not be null — omit the field to take its default.`,
+        { code: ErrorCode.InputWrongType, context: { field } },
+      );
+    }
+  }
+  ensureFiniteWhenPresent(input.dividendYield, 'dividendYield', functionName);
+  const q = input.dividendYield ?? 0;
+
+  const asOfMs = resolveValuationAsOf(input.asOf, functionName);
+  ensureFinite(asOfMs, 'asOf', functionName);
+
+  if (!Array.isArray(input.maturities) || input.maturities.length === 0) {
+    throw new InputError(`${functionName}: at least one maturity (ISO date) is required.`, {
+      code: ErrorCode.InputMissingField,
+      context: { field: 'maturities' },
+    });
+  }
+
+  // Resolve the discrete schedule: validate amounts (matching escrowedSpot), split future from past.
+  const future: ResolvedDividend[] = [];
+  let pastCount = 0;
+  const rawDividends = input.dividends ?? [];
+  if (!Array.isArray(rawDividends)) {
+    throw new InputError(`${functionName}: dividends must be an array of { exDate, amount }.`, {
+      code: ErrorCode.InputWrongType,
+      context: { field: 'dividends' },
+    });
+  }
+  for (const div of rawDividends) {
+    requireArgumentObject(functionName, 'dividend', div);
+    if (!Number.isFinite(div.amount) || div.amount < 0) {
+      throw new InputError(
+        `${functionName}: dividend amount must be a finite, non-negative number, got ${div.amount}.`,
+        { code: ErrorCode.InputOutOfRange, context: { exDate: div.exDate, amount: div.amount } },
+      );
+    }
+    // Ex-dates use the MARKET-OPEN convention (09:30 ET for a date-only label), identical to
+    // `escrowedSpot` — the two must agree or `q_eff(T)` would stop reproducing the escrowed price.
+    const tau = timeToExDateYears(asOfMs, div.exDate, functionName);
+    if (tau > 0) future.push({ tau, amount: div.amount, pv: div.amount * Math.exp(-r * tau) });
+    else pastCount++;
+  }
+  const totalDividendPresentValue = future.reduce((s, d) => s + d.pv, 0);
+
+  // Per-maturity term-structure rows.
+  const points: DividendTermStructurePoint[] = [];
+  for (const maturity of input.maturities) {
+    const T = timeToExpiryYears(asOfMs, maturity, functionName);
+    if (!(T > 0)) {
+      throw new InputError(
+        `${functionName}: maturity ${maturity} is not after asOf (year fraction ${T}).`,
+        {
+          code: ErrorCode.InputNegativeTime,
+          context: { asOf: input.asOf, maturity, T },
+        },
+      );
+    }
+    let dividendPresentValue = 0;
+    let discreteCount = 0;
+    for (const d of future) {
+      if (d.tau < T) {
+        dividendPresentValue += d.pv;
+        discreteCount++;
+      }
+    }
+    // Escrowed spot must stay positive — same contract as escrowedSpot (never emit a NaN forward/yield).
+    if (!(dividendPresentValue < S)) {
+      throw new InputError(
+        `${functionName}: present value of dividends before ${maturity} (${dividendPresentValue}) is not less than the spot (${S}); the escrowed spot would be non-positive.`,
+        { code: ErrorCode.InputOutOfRange, context: { maturity, dividendPresentValue, spot: S } },
+      );
+    }
+    const forward = (S - dividendPresentValue) * Math.exp((r - q) * T);
+    const discreteEquivalentYield = -Math.log(1 - dividendPresentValue / S) / T;
+    const impliedContinuousYield = q + discreteEquivalentYield;
+    const carry = r - impliedContinuousYield;
+    points.push({
+      maturity,
+      yearsToExpiry: T,
+      dividendPresentValue,
+      discreteCount,
+      forward,
+      discreteEquivalentYield,
+      impliedContinuousYield,
+      carry,
+    });
+  }
+  points.sort((a, b) => a.yearsToExpiry - b.yearsToExpiry);
+
+  const warnings: QuantWarning[] = [];
+  if (pastCount > 0) {
+    warnings.push(
+      warning(
+        WarningCode.OptionsDividendsPast,
+        `${functionName}: ${pastCount} dividend${pastCount === 1 ? '' : 's'} with an ex-date on or before asOf ${pastCount === 1 ? 'was' : 'were'} dropped (already paid, so not in any forward).`,
+        'info',
+        { pastCount },
+      ),
+    );
+  }
+  if (future.length === 0) {
+    warnings.push(
+      warning(
+        WarningCode.OptionsDividendsNone,
+        q === 0
+          ? `${functionName}: no dividends supplied — the forwards are the pure cost-of-carry S·e^{rT} (implied yield 0).`
+          : `${functionName}: no discrete dividends supplied — the forwards reflect the continuous yield ${pct(q)} only.`,
+        'info',
+      ),
+    );
+  }
+
+  const dividendModel: DividendModel =
+    future.length > 0 ? 'discreteSchedule' : q === 0 ? 'none' : 'continuousYield';
+
+  return {
+    points,
+    totalDividendPresentValue,
+    continuousYield: q,
+    summary: composeSummary({
+      points,
+      S,
+      totalDividendPresentValue,
+      futureCount: future.length,
+      q,
+    }),
+    assumptions: {
+      conventionsVersion: CONVENTIONS_VERSION,
+      spot: S,
+      riskFreeRate: r,
+      continuousYield: q,
+      dividendModel,
+    },
+    diagnostics: {
+      engine: 'dividend-term-structure',
+      method: 'escrowed-dividend forward + continuous-equivalent yield',
+      converged: true,
+      warnings,
+    },
+  };
+}
+
+/** Compose the one-line term-structure summary. */
+function composeSummary(p: {
+  points: DividendTermStructurePoint[];
+  S: number;
+  totalDividendPresentValue: number;
+  futureCount: number;
+  q: number;
+}): string {
+  const first = p.points[0]!;
+  const last = p.points[p.points.length - 1]!;
+  const n = p.points.length;
+  const expiries = `${n} expir${n === 1 ? 'y' : 'ies'}`;
+  if (p.futureCount === 0) {
+    const carry = p.q === 0 ? 'pure cost-of-carry' : `continuous yield ${pct(p.q)}`;
+    return `No discrete dividends — ${expiries} priced off ${carry}; the implied dividend yield is a flat ${pct(p.q)}.`;
+  }
+  const yieldSpan =
+    n === 1
+      ? `an implied dividend yield of ${pct(first.impliedContinuousYield)}`
+      : `an implied dividend yield of ${pct(first.impliedContinuousYield)} at ${first.yearsToExpiry.toFixed(2)}y and ${pct(last.impliedContinuousYield)} at ${last.yearsToExpiry.toFixed(2)}y`;
+  return `${p.futureCount} upcoming dividend${p.futureCount === 1 ? '' : 's'} worth ${money(p.totalDividendPresentValue)} PV on a ${money(p.S)} spot — across ${expiries}, ${yieldSpan}.`;
+}