@sheetxl/formulas-extended 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/_utils/FinanceCoupon.d.ts

@@ -1,26 +1,4 @@
-/**
- * Shared pure-math helpers for bond pricing and coupon date functions.
- *
- * All formulas follow the Excel spec:
- *   https://support.microsoft.com/en-us/office/financial-functions-reference
- *
- * Date arithmetic delegates to SheetXL's existing date utilities
- * (dateAddMonths, getDaysInMonth, isLastDayOfMonth, getDayCount), and serial
- * <-> Date conversion to FormulaContext's `dateOnly` flavors — same interface
- * SheetXL uses throughout the financial module.
- *
- * Basis codes (used throughout):
- *   0  US 30/360 (NASD)
- *   1  Actual/actual
- *   2  Actual/360
- *   3  Actual/365
- *   4  European 30/360
- *
- * These are plain number-in / number-out helpers that the formula wrappers
- * call after doing all parameter validation and coercion — they touch
- * FormulaContext only for serial<->Date conversion, never IRange or
- * FormulaError.
- */
+import { Omittable, Scalar } from '@sheetxl/primitives';
 /**
  * Returns the signed day count between two Excel serial dates using the given
  * day-count basis.  The result is always positive (or zero) — we clamp
@@ -33,70 +11,117 @@
 export declare function daysBetween(startSerial: number, endSerial: number, basis: number): number;
 /**
  * Previous coupon date (COUPPCD):
- * Returns the Excel serial number of the last coupon date before or on the
- * settlement date.
- *
- * Used by: COUPPCD, COUPDAYBS, COUPDAYS (basis=1), PRICE, YIELD, DURATION…
+ * Returns the Excel serial number of the last coupon date before or on the settlement date.
+ * A coupon date below the calendar answers 0 — Excel's clamp, measured.
  */
 export declare function calculateCouppcd(settlementSerial: number, maturitySerial: number, frequency: number): number;
 /**
  * Next coupon date (COUPNCD):
  * Returns the Excel serial number of the first coupon date after settlement.
- *
- * Used by: COUPNCD, COUPDAYSNC, ODDLPRICE (basis 2 / 3 branch).
  */
 export declare function calculateCoupncd(settlementSerial: number, maturitySerial: number, frequency: number): number;
 /**
- * Days from previous coupon to settlement (COUPDAYBS):
- * The "accrued days" — how many days of the current coupon period have elapsed
- * by the settlement date.
- *
- * Used by: COUPDAYBS, PRICE, YIELD, DURATION, MDURATION.
+ * Number of remaining coupons from settlement to maturity (COUPNUM). `NaN` (the caller's
+ * #NUM!) when the previous coupon date is at or below serial 0 — `COUPNUM(DATE(1900,1,1),
+ * DATE(1900,12,31),4)` is #NUM! while its COUPPCD is 0 (measured).
+ */
+export declare function calculateCoupnum(settlementSerial: number, maturitySerial: number, frequency: number): number;
+/**
+ * Days from previous coupon to settlement (COUPDAYBS): the day count of the basis from the
+ * (clamped) previous coupon date to the settlement — the NASD rules `getDayCount` keeps for
+ * basis 0, actual days for 1–3, the European 30/360 for 4.
  */
 export declare function calculateCoupdaybs(settlementSerial: number, maturitySerial: number, frequency: number, basis: number): number;
 /**
- * Days in the coupon period that contains settlement (COUPDAYS):
- * Basis 1 (actual/actual) counts actual calendar days from PCD to NCD.
- * Basis 3 is always 365/frequency.
- * All 30/360 bases divide 360 by frequency.
- *
- * Used by: COUPDAYS, PRICE, YIELD, DURATION, MDURATION, ODDLPRICE, ODDLYIELD.
+ * Days from settlement to the next coupon date (COUPDAYSNC). Actual days for bases 1–3. The
+ * 30/360 bases are NOT `getDayCount`'s (measured, 556 of 556 rows): the count runs from the
+ * settlement's own day — a 31 is 30, and a February month end is NOT 30 unless the
+ * settlement IS the previous coupon date, in which case the coupon date's unclamped day is
+ * read instead (`COUPDAYSNC(DATE(2011,2,28),DATE(2011,5,31),2,0)` is 92, from day 28;
+ * `COUPDAYSNC(DATE(2011,2,28),DATE(2011,8,29),2,0)` is 179, from the chain's `Feb 29`) — to
+ * the next coupon date carrying the maturity's day unclamped: at basis 0 a February day at or
+ * past the month's end is 30 and a 31 is 30 with no advance into the next month; basis 4
+ * caps both ends at 30.
+ */
+export declare function calculateCoupdaysnc(settlementSerial: number, maturitySerial: number, frequency: number, basis: number): number;
+/**
+ * Days in the coupon period that contains settlement (COUPDAYS). Basis 3 is `365/frequency`
+ * and the 30/360 bases `360/frequency`. Basis 1 is Excel's own construction, measured on
+ * 2,302 rows (fn-battery financial/COUPDAYS + adhoc-coupdays-b1 + adhoc-coupdays-sweep) and
+ * NOT the next coupon minus the previous one (LibreOffice's reading; wrong on 30 of the
+ * battery's 225 rows). Excel walks TWO chains back from maturity: one whose day of month
+ * decays as it is clamped (`Aug 30 → Feb 29 → Aug 29 → Feb 28 → Aug 28`) and one that stays
+ * on the month's last day once a clamp lands there (`Aug 30 → Feb 29 → Aug 31 → Feb 28 →
+ * Aug 31`). The decaying chain is walked to the first date on or before the settlement; if
+ * the coupon after that date is not the same date in both chains, the period is the decaying
+ * chain's, otherwise it is the month-end chain's period around the settlement. So for a Nov 30
+ * maturity paid twice a year a settlement of Dec 15 sits in `Nov 30 → May 30` (181) while a
+ * settlement of May 30 sits in `Nov 30 → May 31` (182) and one of May 31 in `May 31 → Nov 30`
+ * (183). A period that begins below serial 1 is counted in real days (`_periodDays`).
+ *
+ * Used by: COUPDAYS and {@link couponPeriod}.
  */
 export declare function calculateCoupdays(settlementSerial: number, maturitySerial: number, frequency: number, basis: number): number;
 /**
- * Number of remaining coupons from settlement to maturity (COUPNUM):
- * Counts how many (12/frequency)-month backward steps from maturity are needed
- * to pass settlement.
- *
- * Used by: COUPNUM, PRICE, YIELD, DURATION, MDURATION, ODDFPRICE, ODDFYIELD.
+ * The four arguments of the six coupon functions, read in Excel's order — every one is
+ * Excel-declared `any` (a boolean is #VALUE!, an empty argument #N/A, a blank cell 0, a
+ * multi-cell reference does not broadcast: `NoLift<>` on every slot): the two dates
+ * are coerced and validated (#NUM! for a serial outside the calendar or a settlement not
+ * strictly before the maturity once both are truncated), then the frequency is read and
+ * validated (1, 2 or 4 after truncation), then the basis — so
+ * `COUPDAYS(DATE(2020,1,1),DATE(2019,1,1),"x",0)` is #NUM! and so is the same with a text
+ * basis, while a text frequency against a bad basis is #VALUE!. Basis truncates; a negative
+ * one is #NUM! before truncation.
  */
-export declare function calculateCoupnum(settlementSerial: number, maturitySerial: number, frequency: number): number;
+export declare function readCouponArgs(settlement: Omittable<Scalar>, maturity: Omittable<Scalar>, frequency: Omittable<Scalar>, basis: Omittable<Scalar>): {
+    settlement: number;
+    maturity: number;
+    frequency: number;
+    basis: number;
+};
 /**
- * ODDFPRICE core:
- * Prices a bond with an irregular (short or long) first coupon period.
- *
- * Dispatches to the short-coupon or long-coupon sub-function depending on
- * whether DFC < E (short first period) or DFC >= E (long first period).
- *
- * All arguments are already validated scalars.  Returns NaN on degenerate
- * inputs (the formula wrapper turns NaN → #NUM!).
- *
- * Reference:
- *   https://support.microsoft.com/en-us/office/oddfprice-function-d7d664a8-34df-4233-8d2b-922bcf6a69e1
+ * The coupon-period numbers PRICE, YIELD, DURATION and MDURATION are built on, as Excel
+ * composes them (measured against Excel's own COUPNUM/COUPDAYBS/COUPDAYS/COUPDAYSNC answers on
+ * 572 shapes, fn-battery financial/PRICE + /DURATION, 2026-08-28): `N` is COUPNUM (NaN, the
+ * caller's #NUM!, when the previous coupon is below the calendar), `A` is COUPDAYBS, and the
+ * period length `E` is COUPDAYS — EXCEPT at basis 1, where it is the real span from the
+ * previous coupon to the next (`COUPDAYBS + COUPDAYSNC`), not COUPDAYS' two-chain value; the
+ * two differ on the month-end and February maturities (22 of the 225 basis-1 shapes). `DSC` is
+ * `E − A`, never COUPDAYSNC.
  */
-export declare function calculateOddFPrice(settlementSerial: number, maturitySerial: number, issueSerial: number, firstCouponSerial: number, rate: number, yld: number, redemption: number, frequency: number, basis: number): number;
+export declare function couponPeriod(settlementSerial: number, maturitySerial: number, frequency: number, basis: number): {
+    N: number;
+    A: number;
+    E: number;
+    DSC: number;
+};
 /**
- * Standard coupon bond price.
- *
- * The closed-form formula per $100 face value from the Excel spec:
- *   https://support.microsoft.com/en-us/office/price-function-3ea9deac-8dfa-436f-a7c8-17ea02c21b0a
- *
- * Special-cased for N=1 (single remaining coupon period) where the standard
- * summation degenerates and the spec provides a simpler formula.
- *
- * Used by: PRICE, YIELD (via Newton inversion).
+ * Standard coupon bond price per $100 face value — the doc's closed form over
+ * {@link couponPeriod}'s numbers: with one coupon left `(coupon + redemption) / (1 + DSC/E ·
+ * yld/f) − coupon · A/E` (linear, not the power form), otherwise the redemption and each coupon
+ * discounted by `(1 + yld/f)^(k − 1 + DSC/E)` less the accrued coupon. Measured bit-for-bit on
+ * PRICE's battery (fn-battery financial/PRICE, 2026-08-28).
+ *
+ * The grouping is measured too, as ODDFPRICE's is: the coupon sum is accumulated on its own,
+ * forward, then the redemption term is added to it and the accrued coupon subtracted. Starting
+ * the accumulator at the redemption instead costs 146 of PRICE's 779 census rows and 74 of
+ * YIELD's 785 (SXL_CENSUS over the financial suite, 2026-09-09) — the terms and the divisions
+ * are identical either way, only the order the additions round in differs. It is visible in
+ * YIELD because that answer is a PARTIAL iterate.
+ *
+ * Used by: PRICE, YIELD.
  */
 export declare function calculatePrice(settlementSerial: number, maturitySerial: number, rate: number, yld: number, redemption: number, frequency: number, basis: number): number;
+/**
+ * `d/dy` of {@link calculatePrice}, term by term — the slope YIELD's Newton divides by. Analytic,
+ * not a difference quotient: a finite difference of any step reproduces neither the hundred-step
+ * answers of a redemption that dwarfs the price nor the partially-converged ones (fn-battery
+ * financial/adhoc-yield-fingerprint, 2026-09-09). A term that overflows makes the slope infinite,
+ * which the caller answers as #NUM!.
+ *
+ * Used by: YIELD.
+ */
+export declare function calculatePriceSlope(settlementSerial: number, maturitySerial: number, rate: number, yld: number, redemption: number, frequency: number, basis: number): number;
 /**
  * Macaulay duration of a coupon bond.
  *
@@ -123,19 +148,4 @@ export declare function calculateDuration(settlementSerial: number, maturitySeri
  */
 export declare function calculateDDB(cost: number, salvage: number, life: number, period: number, // 1-based period number
 factor: number): number;
-/**
- * Returns true if the settlement and maturity dates are aligned to coupon
- * dates — i.e., the day-of-month matches and the month difference is an exact
- * multiple of (12/frequency).
- *
- * Used by ODDFPRICE / ODDFYIELD / ODDLPRICE / ODDLYIELD validators.
- */
-export declare function isDatesAreAlignedToCoupon(date1Serial: number, date2Serial: number, frequency: number): boolean;
-/**
- * Returns true if calculateCouppcd(d1, d2, frequency) >= 0.
- *
- * Used by ODDFPRICE / ODDFYIELD validators.
- */
-export declare function isCouppcdIsNonNegative(date1Serial: number, date2Serial: number, frequency: number): boolean;
-export declare function isValidFrequency(frequency: number): boolean;
 //# sourceMappingURL=FinanceCoupon.d.ts.map

package/types/src/_utils/FinanceDate.d.ts

@@ -23,4 +23,28 @@ export declare function isMoreThanOneYearAfter(startSerial: number, endSerial: n
  * `setMonth` which truncates automatically.
  */
 export declare function dateAddMonths(date: Date, months: number): Date;
+/**
+ * Calendar fields of a serial date. `m` is 1-based.
+ */
+export interface DateFields {
+    y: number;
+    m: number;
+    d: number;
+}
+/** Days in month `m` (1-based), on the real Gregorian calendar. */
+export declare const daysInMonth: (y: number, m: number) => number;
+/** True when `x` is the last day of its month. */
+export declare const isMonthEnd: (x: DateFields) => boolean;
+/** The workbook calendar's fields for a serial. */
+export declare function getDateFields(serial: number): DateFields;
+/**
+ * The serial of calendar fields, extended linearly BELOW the calendar (1899-12-31 is 0, and on
+ * down) and with a day past the month's end OVERFLOWING into the next month — a "Feb 30" is
+ * Mar 1. The coupon chains that walk off either end of the calendar are measured against Excel
+ * on those extended values, so they need an arithmetic that keeps producing them
+ * (fn-battery financial/ACCRINT and /ODDLPRICE).
+ */
+export declare function getSerialOfFields(y: number, m: number, d: number): number;
+/** The fields `months` months on from `x`, the day clamped to the destination month. */
+export declare function addMonthsClamped(x: DateFields, months: number): DateFields;
 //# sourceMappingURL=FinanceDate.d.ts.map

package/types/src/_utils/FinanceDayCount.d.ts

@@ -77,4 +77,50 @@ export declare function getDayCount(startSerial: number, endSerial: number, basi
  *
  */
 export declare function getDays360US(startSerial: number, endSerial: number): number;
+/** The last serial of the 1900 calendar (9999-12-31). */
+export declare const MAX_SERIAL_DATE = 2958465;
+/**
+ * Excel's date-slot domain for the day-count family, measured on DAYS360, YEARFRAC, DATEDIF
+ * and the six coupon functions (fn-battery financial/*, 2026-08-28): the RAW value must not be
+ * negative (`-1E-9` is #NUM!) and the truncated serial must not pass 9999-12-31 (`2958465.9` is
+ * a legal 9999-12-31). The fraction is otherwise discarded by every function in the family.
+ */
+export declare function isSerialDateInRange(serial: number): boolean;
+/**
+ * `YEARFRAC` — measured against Excel 16.0 (fn-battery financial/YEARFRAC, 2026-08-28). Both
+ * serials are truncated first, the earlier date becomes the start, and basis 0 is then the
+ * SIGNED NASD count: Excel orders the dates but never takes a magnitude, so
+ * `YEARFRAC(59,60,0)` — 1900-02-28, a real month end, against the phantom 1900-02-29 that is
+ * not — is `-1/360`. The other bases cannot go negative once ordered. The caller has validated
+ * the serials and the basis.
+ */
+export declare function getYearFrac(startSerial: number, endSerial: number, basis: number): number;
+/**
+ * The years to maturity a bond-yield ITERATION starts from — not `YEARFRAC`, and not the coupon
+ * count over the frequency. Whole years are stepped off the settlement (the day clamped to each
+ * destination month) and the remainder is the basis's own day count over the basis's year: the
+ * 30/360 counts over 360 at bases 0 and 4, real days over 360 at basis 2 and over 365 at basis 3,
+ * and real days over the MATURITY'S OWN year at basis 1 — 366 out of a leap year, whatever the
+ * remainder itself covers. Basis 0's February here is the LEGACY calendar's: a Feb 29 start is a
+ * month end and a Feb 28 is not, which is neither `getDayCount`'s rule (the real calendar's month
+ * end, so Feb 28 counts too) nor `getDays360US`'s (which also lets the conversion steer the end).
+ *
+ * Measured on 1,154 rows where the answer depends on nothing else (fn-battery
+ * financial/adhoc-yield-n, -n2, -n3), 2026-09-09.
+ *
+ * Used by: YIELD, ODDFYIELD.
+ */
+export declare function getYearsToMaturity(settlement: number, maturity: number, basis: number): number;
+/**
+ * The stub-period day count of AMORLINC/AMORDEGRC (the year fraction is `days / yearDays`, and
+ * the caller groups that as Excel does) — measured against Excel 16.0 (fn-battery
+ * financial/AMORLINC, /AMORDEGRC, 2026-08-28), and NOT YEARFRAC's: serials are truncated, the
+ * 30/360 bases count days as `getDayCount` does over 360, basis 3 is actual days over 365, and
+ * basis 1 is actual days over the length of the PURCHASE year (366 only when that year is a
+ * Gregorian leap year — 1900 is not — whatever the span crosses; 2007-12-31 → 2008-12-31 is
+ * 366/365), and in both actual bases a real Feb 29 counts as the 28th (`_feb29AsFeb28`). A zero-day stub is a whole period (`purchase = first period`, or Dec 30 → Dec 31
+ * at basis 0), and a stub longer than a year is not capped. Basis 2 is not accepted by either
+ * function; the caller has refused it before this is called.
+ */
+export declare function getAmorDayCount(purchased: number, firstPeriod: number, basis: number): DayCount;
 //# sourceMappingURL=FinanceDayCount.d.ts.map

package/types/src/_utils/FinanceOdd.d.ts

@@ -0,0 +1,93 @@
+import { Omittable, Scalar } from '@sheetxl/primitives';
+/**
+ * The odd-coupon securities' shared machinery — the quasi-coupon chain of an irregular period
+ * and the day-count sums the price and yield forms are built from, measured against Excel 16.0
+ * (fn-battery financial/ODDLPRICE + /ODDLYIELD + /ODDFPRICE and the `adhoc-oddl-*` /
+ * `adhoc-oddf-*` probes, 2026-08-28/29).
+ */
+/**
+ * `(settlement, maturity, …dates, …numbers, frequency, [basis])` as the four ODD functions read
+ * it: every slot is Excel-declared `any` (a boolean is #VALUE!, an empty argument #N/A, a blank
+ * cell 0, a multi-cell reference does not broadcast — `NoLift<>` on every slot), and the order is
+ * coupon six's, not PRICE's. Each DATE is coerced and range-checked as it is read, so a negative
+ * `last_interest` is #NUM! over a text frequency; then the numbers are coerced; then the
+ * frequency is validated (1, 2 or 4 after truncation); then the BASIS, last. Only after all of
+ * that do the date ORDER and the signs decide — a text frequency beats a settlement that is
+ * after its maturity. Serials come back truncated.
+ */
+export declare function readOddArgs(dates: Omittable<Scalar>[], numbers: Omittable<Scalar>[], frequency: Omittable<Scalar>, basis: Omittable<Scalar>): {
+    dates: number[];
+    numbers: number[];
+    frequency: number;
+    basis: number;
+};
+/**
+ * The three day-count sums of the odd LAST period `[lastInterest, maturity]`, in coupon-period
+ * units — the numbers ODDLPRICE and ODDLYIELD are built from. Measured on 1,780
+ * (shape, frequency, basis) triples, each sum exact (`fn-battery/financial/fit-oddl.mjs`).
+ *
+ * It takes TWO chains, as COUPDAYS' basis 1 did (batch 3): the DECAYING chain anchored at
+ * `lastInterest` gives the period ends and their lengths, while the STICKY chain decides only
+ * which period the maturity lands in — so an Aug 31 maturity against a decayed Aug 28 boundary
+ * is still inside the period that ENDS there and overhangs it by three days.
+ *
+ * Over the periods `[B₀ = lastInterest, B₁] … [B_{J−1}, B_J]`:
+ *
+ * - `A` and `DSC` walk their span (`lastInterest → settlement`, `settlement → maturity`) period
+ *   by period, no period contributing more than itself — a 31st period end counted raw runs one
+ *   day past its own length.
+ * - `DC` counts every period 1 except the last, which is measured BACKWARD from its end,
+ *   `(NL − count(maturity, B_J)) / NL`. That is what makes `DC ≠ A + DSC` at basis 0.
+ *
+ * A chain that leaves the calendar is #NUM!: past its end going forward, and — stepping BACK
+ * from the MATURITY to the first date at or below `lastInterest` — below serial 1 going back
+ * (measured: a ladder landing on serial 1 computes, one landing on serial 0 is #NUM!).
+ */
+export declare function oddLastSums(settlement: number, maturity: number, lastInterest: number, frequency: number, basis: number): {
+    A: number;
+    DC: number;
+    DSC: number;
+};
+/**
+ * The numbers ODDFPRICE's form is built from — `N` regular coupons after `firstCoupon`, the
+ * accrued sum `A` and the first coupon's sum `DC` (both in coupon-period units), and `u`, the
+ * fractional exponent every cash flow after the settlement is discounted by. Measured on 1,125
+ * (shape, frequency, basis) triples, the four sums solved out of Excel by linearity
+ * (`fn-battery/financial/oddf-model.mjs`, `verify-oddf.mjs`, `adhoc-oddf-*`, 2026-08-29).
+ *
+ * The maturity must sit on `firstCoupon`'s grid — `COUPPCD(firstCoupon, maturity) = firstCoupon`
+ * — and the doc's two branches are real, on DIFFERENT date machinery. `E` is the regular period
+ * around the settlement on that grid, PRICE's {@link couponPeriod} (`COUPDAYBS + COUPDAYSNC` at
+ * basis 1); `DFC` the basis's count issue → firstCoupon:
+ *
+ * - `DFC = E` is #NUM! — an odd period that is exactly a regular one.
+ * - SHORT (`DFC < E`): one period, every count over `E` — `A = issue→settlement`, `DC = DFC`,
+ *   `u = settlement→firstCoupon`, the last straight from the settlement (the NASD advance
+ *   included). `N` is `COUPNUM(settlement, maturity) − 1`, which counts a grid date between the
+ *   settlement and the first coupon when there is one (a settlement in the gap between a
+ *   decayed boundary and its sticky twin).
+ * - LONG (`DFC > E`): `COUPNUM(issue, firstCoupon)` quasi periods on the STICKY grid, their
+ *   boundaries walked DECAYED back from `firstCoupon` (each step subtracts `12/f` months from
+ *   the previous date and clamps: an Aug 31 anchor semiannual is Feb 28, then Aug 28) — so the
+ *   earliest period can end at or before the issue and count nothing. `NL` is each period's
+ *   own actual span at basis 1, `360/f` or `365/f` elsewhere; `A` walks issue → settlement as
+ *   days over `NL`; `DC` is the issue's period as days over `NL` and every later period exactly
+ *   1 (the doc's DCᵢ — visible at bases 2 and 3). The exponent `u = Nq + DSC/E` is on the
+ *   sticky grid instead: `DSC = E − COUPDAYBS` at bases 0/1/4 and the actual days to the next
+ *   grid date at 2/3, and `Nq` is `COUPNUM(settlement, firstCoupon) − 1` PLUS ONE on a
+ *   month-end first coupon — Excel discounts every cash flow one period too far — unless the
+ *   settlement is itself a month end or its month holds an earlier quasi-coupon date
+ *   (`adhoc-oddf-nq`, 957 settlements swept day by day).
+ *
+ * A chain that walks below the calendar is #NUM! in either branch (a settlement in the first
+ * days of 1900 has quasi dates in 1899).
+ */
+export declare function oddFirstSums(settlement: number, maturity: number, issue: number, firstCoupon: number, frequency: number, basis: number): {
+    N: number;
+    A: number;
+    DC: number;
+    u: number;
+};
+/** The ATP arithmetic of the family: a product that overflowed is 0 (batch 4's `overflowIsZero`). */
+export declare const zeroIfOverflow: (value: number) => number;
+//# sourceMappingURL=FinanceOdd.d.ts.map

package/types/src/_utils/FinanceSecurity.d.ts

@@ -0,0 +1,84 @@
+import { Omittable, Scalar } from '@sheetxl/primitives';
+/**
+ * Argument readers for the securities functions — every slot Excel-declared `any`, read in the
+ * order Excel reads them (measured against Excel 16.0, fn-battery financial/*, 2026-08-28).
+ *
+ * Two orders exist in the family. The discount securities (DISC PRICEDISC YIELDDISC INTRATE
+ * RECEIVED) CONVERT from the last slot to the first and only then look for errors in slot
+ * order; ACCRINTM, ACCRINT and the coupon functions convert and validate each slot from the
+ * first. Each function names its own.
+ */
+/** The basis slot: omitted or blank is 0, text parses, a boolean is #VALUE!, out of 0–4 after truncation is #NUM!. */
+export declare function readBasis(basis: Omittable<Scalar>): number;
+/** The two dates of a security, truncated, both in the calendar and the settlement strictly first — else #NUM!. */
+export declare function checkDateOrder(settlement: number, maturity: number): {
+    settlement: number;
+    maturity: number;
+};
+/**
+ * `(settlement, maturity, x, y, [basis])` as DISC, PRICEDISC, YIELDDISC, INTRATE and RECEIVED
+ * read it: the basis FIRST — coerced and range-checked, so a text basis is #VALUE!, a basis of 5
+ * is #NUM! and an error there is the answer whatever an earlier slot holds — then the four
+ * slots from the first, each coerced (its error or a text answered) before the next is read;
+ * then the domain: serials in the calendar, `settlement < maturity` once truncated, `x > 0`,
+ * `y > 0`. An omitted required slot is #N/A, a blank cell 0.
+ */
+export declare function readDiscountArgs(settlement: Omittable<Scalar>, maturity: Omittable<Scalar>, x: Omittable<Scalar>, y: Omittable<Scalar>, basis: Omittable<Scalar>): {
+    settlement: number;
+    maturity: number;
+    x: number;
+    y: number;
+    basis: number;
+};
+/**
+ * `(settlement, maturity, x)` as TBILLEQ, TBILLPRICE and TBILLYIELD read it: each slot coerced
+ * from the first (an error or a text is answered before the next slot is read, so a text `x`
+ * beats swapped dates), then the domain: both serials in the calendar, `settlement < maturity`
+ * once truncated, the maturity at most one calendar year out ({@link _anniversary}), `x > 0`.
+ * `days` is the actual span of the truncated serials.
+ */
+export declare function readTbillArgs(settlement: Omittable<Scalar>, maturity: Omittable<Scalar>, x: Omittable<Scalar>): {
+    settlement: number;
+    maturity: number;
+    x: number;
+    days: number;
+};
+/**
+ * `(settlement, maturity, issue, rate, x, [basis])` as PRICEMAT and YIELDMAT read it: the basis
+ * first (coerced and range-checked, so a text basis is #VALUE! and a basis of 5 #NUM! whatever
+ * the other slots hold, and an error there wins), then the five slots from the first, each
+ * coerced before the next is read; then the domain — every serial in the calendar,
+ * `issue < settlement < maturity` once truncated, and the signs the caller checks. The three
+ * day counts come back with `DSM` as `DIM − A`, which is how Excel has it: at basis 0 a Feb 28
+ * settlement against a Mar 31 maturity counts 32 days inside a Jan 31 issue (60 − 28), where
+ * the NASD count of the pair alone is 31. `B` is the year length of the issue→settlement pair.
+ */
+export declare function readMatArgs(settlement: Omittable<Scalar>, maturity: Omittable<Scalar>, issue: Omittable<Scalar>, rate: Omittable<Scalar>, x: Omittable<Scalar>, basis: Omittable<Scalar>): {
+    rate: number;
+    x: number;
+    DIM: number;
+    DSM: number;
+    A: number;
+    B: number;
+};
+/**
+ * `(settlement, maturity, …numbers, frequency, [basis])` as PRICE, YIELD, DURATION and
+ * MDURATION read it (measured on all four, fn-battery 2026-08-28). PRICE and YIELD read the
+ * basis FIRST — coerced and range-checked, so a text basis is #VALUE! and a 5 is #NUM! whatever
+ * else is wrong, and an error there wins over an error in the settlement; DURATION and
+ * MDURATION read it LAST (`basisLast`), the coupon functions' way. In between, the settlement
+ * and the maturity are each coerced and checked against the calendar before the next slot is
+ * read (a negative settlement is #NUM! over a text frequency), then the numeric slots are
+ * coerced, then the frequency is coerced and validated (1, 2 or 4 after truncation); the date
+ * order (`settlement < maturity` once truncated) and the signs of the numbers come last.
+ */
+export declare function readBondArgs(settlement: Omittable<Scalar>, maturity: Omittable<Scalar>, numbers: Omittable<Scalar>[], frequency: Omittable<Scalar>, basis: Omittable<Scalar>, basisLast?: boolean): {
+    settlement: number;
+    maturity: number;
+    numbers: number[];
+    frequency: number;
+    basis: number;
+};
+/** Excel's Analysis-ToolPak arithmetic answers 0 for a product that overflowed (measured on ACCRINTM, TBILLEQ, TBILLPRICE, PRICEMAT). */
+export declare const overflowIsZero: (value: number) => number;
+//# sourceMappingURL=FinanceSecurity.d.ts.map

package/types/src/_utils/FinanceUtils.d.ts

@@ -1,4 +1,25 @@
 import { IRuntime } from '@sheetxl/primitives';
+/**
+ * The secant step cap shared by RATE and IRR — Excel gives up after 200, not the documented 20
+ * (measured on one 24-period loan: a path of 200 steps converges, one of 203 is #NUM!). IRR runs
+ * the same iteration on the discount factor rather than the rate, so the cap is one fact.
+ */
+export declare const RATE_MAX_ITERATIONS = 200;
+/**
+ * The currency format Excel gives a financial result cell, in the runtime's locale.
+ *
+ * @remarks
+ * Which functions auto-format is a per-function fact and was MEASURED across the category
+ * (2026-08-29, `Range.NumberFormat` read after a `Formula2` entry into a General cell): the
+ * legacy core formats by result kind — money through this helper (NPV PMT IPMT PPMT FV PV SLN
+ * SYD DB DDB VDB) and a rate as `0%` (IRR MIRR RATE) — while everything ATP-era or added later
+ * sets nothing at all (XIRR XNPV NPER ISPMT RRI PDURATION EFFECT NOMINAL FVSCHEDULE CUMIPMT
+ * CUMPRINC and every security, COUPNCD and COUPPCD included).
+ *
+ * Excel applies it at ENTRY, before it knows the answer, so a `#NUM!`, `#VALUE!` or `#DIV/0!`
+ * cell carries the format too. That is why every `formatResults` call in this category LEADS its
+ * body instead of following the domain guards.
+ */
 export declare const defaultCurrencyFormat: (runtime: IRuntime) => string;
 /**
  * `base ^ exponent` as Excel evaluates it (the `^` operator, POWER, and the powers inside the
@@ -14,7 +35,22 @@ export declare const defaultCurrencyFormat: (runtime: IRuntime) => string;
  * on the sensitive rows (`FV(1E-15,12.5,…)` is 2 digits on `Math.pow`, exact here), and equal to
  * it everywhere else measured.
  *
- * A zero base follows the `^` operator: `0^0` is #NUM! and `0^negative` is #DIV/0!.
+ * A zero base follows the `^` operator: `0^0` is #NUM! and `0^negative` is #DIV/0!. So does a
+ * negative base under a fractional exponent: real only when the exponent's reciprocal, read at 15
+ * significant digits, is an odd integer — `FV(-3,1/3,1)` is -0.7533 — and #NUM! otherwise.
  */
 export declare const excelPow: (base: number, exponent: number) => number;
+/**
+ * Excel's C `(int)` cast of an argument: truncation toward zero, and INT_MIN for anything out of
+ * the 32-bit range (the x64 `cvttsd2si` convention), NaN included. Measured on DB (fn-battery,
+ * 2026-08-28): `DB(…,3E9,2E9)` is #NUM! because only `life` overflows to INT_MIN while
+ * `DB(…,1E10,5E9)` is 0 because both do.
+ */
+export declare const excelInt32: (value: number) => number;
+/**
+ * Round to `digits` decimals as Excel's ROUND does: ties away from zero, decided on the value's
+ * 15-significant-digit decimal form rather than its binary one — `550 · 0.45` is
+ * 247.49999999999997 in double and Excel rounds it to 248 (AMORDEGRC, measured 2026-08-28).
+ */
+export declare const excelRound: (value: number, digits?: number) => number;
 //# sourceMappingURL=FinanceUtils.d.ts.map

package/types/src/_utils/LeastSquares.d.ts

@@ -1,4 +1,4 @@
-import { FormulaError, IRange } from '@sheetxl/primitives';
+import { FormulaError, IRange, IReferenceRange, Scalar } from '@sheetxl/primitives';
 /**
  * How Excel reads `known_y` / `known_x` into (observations x predictors).
  *
@@ -33,15 +33,22 @@ export interface RegressionData {
 /**
  * Reads `known_y` / `known_x` the way the whole LINEST family does.
  *
- * STRICT membership: any non-numeric member of either range — text, boolean, or BLANK — is
- * `#VALUE!`. There is no skipping and no coercion here (`LINEST({2;TRUE;5;4}, …)` and
- * `LINEST({2;"3";5;4}, …)` are both `#VALUE!`), which is the opposite of the paired statistics
- * (CORREL/SLOPE/…) where a non-numeric member drops its pair. Dropping a member here would shift
- * every later observation against its x and silently return a different fit.
+ * The SHAPES are judged first — a mismatch is #REF! whatever the members hold — and then the
+ * members, in order. Membership is STRICT: any non-numeric member of either range — text,
+ * boolean, or BLANK — is `#VALUE!`. There is no skipping and no coercion here
+ * (`LINEST({2;TRUE;5;4}, …)` and `LINEST({2;"3";5;4}, …)` are both `#VALUE!`), which is the
+ * opposite of the paired statistics (CORREL/SLOPE/…) where a non-numeric member drops its pair.
+ * Dropping a member here would shift every later observation against its x and silently return a
+ * different fit.
  *
- * @throws #VALUE! on a non-numeric member, #REF! on a dimension mismatch.
+ * `log` is the LOGEST/GROWTH read: each y is checked as it is met, so a y at or below zero is
+ * #NUM! even when a text member sits later in the range, and the ys come back as their logarithms.
+ *
+ * @throws #VALUE! on a non-numeric member, #REF! on a dimension mismatch, #NUM! on a y without a
+ * logarithm.
  */
-export declare const readRegressionData: (knownYs: IRange, knownXs: IRange | undefined) => RegressionData;
+export declare const readRegressionData: (knownYs: IRange, knownXs: IRange | undefined, log?: boolean) => RegressionData;
+export declare const overLogical: (value: boolean | IReferenceRange | IReferenceRange[] | null | undefined, absent: boolean, compute: (value: boolean) => Scalar[][]) => Scalar[][];
 /**
  * Reads a `new_x` range into (observations x k), and reports the shape its predictions spill into.
  *
@@ -57,15 +64,6 @@ export declare const readNewX: (newXs: IRange, data: RegressionData) => {
     rows: number;
     cols: number;
 };
-/**
- * `ln(y)` for the log-space members of the family (LOGEST / GROWTH).
- *
- * A y at or below zero has no logarithm, and Excel reports that as #NUM! — a distinct outcome from
- * the #VALUE! a non-numeric member gets, so the two checks stay separate.
- *
- * @throws #NUM! when any y is <= 0.
- */
-export declare const toLogYs: (ys: number[]) => number[];
 /**
  * Evaluates a fit over `new_x`, in the shape Excel spills.
  *
@@ -73,7 +71,7 @@ export declare const toLogYs: (ys: number[]) => number[];
  * the fitted values, so a 6x2 `known_y` spills 6x2. Otherwise the shape comes from `new_x`
  * ({@link readNewX} decides whether that is element-wise or one row/column per observation).
  */
-export declare const predictInShape: (data: RegressionData, newXs: IRange | undefined, predict: (x: number[]) => number) => number[][];
+export declare const predictInShape: (data: RegressionData, newXs: IRange | undefined, predict: (x: number[]) => Scalar) => Scalar[][];
 /** A fitted model — coefficients in Excel's slot order plus everything the stats grid needs. */
 export interface RegressionFit {
     /**
@@ -81,11 +79,11 @@ export interface RegressionFit {
      * belongs to the LAST column of `known_x`.
      */
     coefficients: number[];
-    /** Standard errors in the same slot order. `se[k]` is meaningless when `!useConst` (Excel: #N/A). */
+    /** Standard errors in the same slot order. `se[k]` is meaningless when `!constant` (Excel: #N/A). */
     standardErrors: number[];
     /** Number of predictors actually used — a column dropped for rank deficiency does not count. */
     kEffective: number;
-    /** `n - kEffective - (useConst ? 1 : 0)`. */
+    /** `n - kEffective - (constant ? 1 : 0)`. */
     df: number;
     /** Standard error of the y estimate. 0 when `df <= 0`, which is what Excel returns. */
     sey: number;
@@ -111,7 +109,7 @@ export interface RegressionFit {
  * The same path covers "not enough observations": with n = 2 and 2 predictors the second column
  * has no residual left and is dropped, which is exactly what Excel returns.
  */
-export declare const fitLeastSquares: (ys: number[], xs: number[][], useConst: boolean) => RegressionFit;
+export declare const fitLeastSquares: (ys: number[], xs: number[][], constant: boolean) => RegressionFit;
 /**
  * The `stats = TRUE` grid: 5 rows x (k + 1) columns.
  *
@@ -127,5 +125,5 @@ export declare const fitLeastSquares: (ys: number[], xs: number[][], useConst: b
  * `se(b)` when the intercept was not fitted — the b slot itself still carries a value (0 for
  * LINEST, 1 for LOGEST), it is only its error that is #N/A.
  */
-export declare const buildStatsGrid: (fit: RegressionFit, coefficients: number[], useConst: boolean) => (number | FormulaError.Known)[][];
+export declare const buildStatsGrid: (fit: RegressionFit, coefficients: (number | FormulaError.Known)[], constant: boolean) => (number | FormulaError.Known)[][];
 //# sourceMappingURL=LeastSquares.d.ts.map