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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/formulas-extended",
   "description": "Formulas Enterprise - TypeScript formulas compatible with Excel built-ins.",
-  "version": "0.8.0-beta.1",
+  "version": "0.8.0-beta.10",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -9,13 +9,12 @@
       "types": "./types/index.d.ts",
       "browser": "./browser/esm/index.mjs",
       "node": "./node/esm/index.mjs",
-      "import": "./browser/esm/index.mjs",
-      "require": "./browser/cjs/index.cjs"
+      "default": "./browser/esm/index.mjs"
     }
   },
   "types": "./types/index.d.ts",
   "module": "./browser/esm/index.mjs",
-  "main": "./browser/cjs/index.cjs",
+  "main": "./browser/esm/index.mjs",
   "sideEffects": false,
   "engineStrict": true,
   "homepage": "https://sheetxl.com",
@@ -37,7 +36,7 @@
     "formulas"
   ],
   "dependencies": {
-    "@sheetxl/primitives": "^0.8.0-beta.1",
-    "@sheetxl/scripting": "^0.8.0-beta.1"
+    "@sheetxl/primitives": "^0.8.0-beta.10",
+    "@sheetxl/scripting": "^0.8.0-beta.10"
   }
 }

package/types/src/.generated/decl/financial/Annuity.decl.d.ts

@@ -0,0 +1,5 @@
+import { MinifiedDeclarations, MinifiedEnums } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export declare const enums: MinifiedEnums;
+export default declarations;
+//# sourceMappingURL=Annuity.decl.d.ts.map

package/types/src/.generated/decl/financial/{Financial.decl.d.ts → Cashflow.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=Financial.decl.d.ts.map
+//# sourceMappingURL=Cashflow.decl.d.ts.map

package/types/src/.generated/decl/financial/Convert.decl.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=Convert.decl.d.ts.map

package/types/src/.generated/decl/financial/Coupon.decl.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=Coupon.decl.d.ts.map

package/types/src/.generated/decl/financial/{Financial2.decl.d.ts → Depreciation.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=Financial2.decl.d.ts.map
+//# sourceMappingURL=Depreciation.decl.d.ts.map

package/types/src/.generated/decl/financial/Growth.decl.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=Growth.decl.d.ts.map

package/types/src/.generated/decl/financial/{ODD.decl.d.ts → Odd.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=ODD.decl.d.ts.map
+//# sourceMappingURL=Odd.decl.d.ts.map

package/types/src/.generated/decl/financial/{Financial3.decl.d.ts → STOCKHISTORY.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=Financial3.decl.d.ts.map
+//# sourceMappingURL=STOCKHISTORY.decl.d.ts.map

package/types/src/.generated/decl/financial/Security.decl.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=Security.decl.d.ts.map

package/types/src/.generated/decl/financial/{Financial4.decl.d.ts → SecurityMaturity.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=Financial4.decl.d.ts.map
+//# sourceMappingURL=SecurityMaturity.decl.d.ts.map

package/types/src/.generated/decl/{statistical/TTEST.decl.d.ts → financial/TBill.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=TTEST.decl.d.ts.map
+//# sourceMappingURL=TBill.decl.d.ts.map

package/types/src/.generated/decl/lookupReference/GroupBy.decl.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=GroupBy.decl.d.ts.map

package/types/src/.generated/decl/lookupReference/PivotBy.decl.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=PivotBy.decl.d.ts.map

package/types/src/.generated/decl/statistical/{ETS.decl.d.ts → Ets.decl.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDeclarations } from '@sheetxl/scripting';
 declare const declarations: MinifiedDeclarations;
 export default declarations;
-//# sourceMappingURL=ETS.decl.d.ts.map
+//# sourceMappingURL=Ets.decl.d.ts.map

package/types/src/.generated/decl/statistical/TTest.decl.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDeclarations } from '@sheetxl/scripting';
+declare const declarations: MinifiedDeclarations;
+export default declarations;
+//# sourceMappingURL=TTest.decl.d.ts.map

package/types/src/.generated/desc/financial/Annuity.desc.d.ts

@@ -0,0 +1,5 @@
+import { MinifiedDescriptors, MinifiedEnumDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export declare const enums: MinifiedEnumDescriptors;
+export default descriptors;
+//# sourceMappingURL=Annuity.desc.d.ts.map

package/types/src/.generated/desc/financial/{Financial.desc.d.ts → Cashflow.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=Financial.desc.d.ts.map
+//# sourceMappingURL=Cashflow.desc.d.ts.map

package/types/src/.generated/desc/financial/Convert.desc.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=Convert.desc.d.ts.map

package/types/src/.generated/desc/financial/Coupon.desc.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=Coupon.desc.d.ts.map

package/types/src/.generated/desc/financial/{Financial2.desc.d.ts → Depreciation.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=Financial2.desc.d.ts.map
+//# sourceMappingURL=Depreciation.desc.d.ts.map

package/types/src/.generated/desc/financial/Growth.desc.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=Growth.desc.d.ts.map

package/types/src/.generated/desc/financial/{ODD.desc.d.ts → Odd.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=ODD.desc.d.ts.map
+//# sourceMappingURL=Odd.desc.d.ts.map

package/types/src/.generated/desc/financial/{Financial3.desc.d.ts → STOCKHISTORY.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=Financial3.desc.d.ts.map
+//# sourceMappingURL=STOCKHISTORY.desc.d.ts.map

package/types/src/.generated/desc/financial/Security.desc.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=Security.desc.d.ts.map

package/types/src/.generated/desc/financial/{Financial4.desc.d.ts → SecurityMaturity.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=Financial4.desc.d.ts.map
+//# sourceMappingURL=SecurityMaturity.desc.d.ts.map

package/types/src/.generated/desc/{statistical/TTEST.desc.d.ts → financial/TBill.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=TTEST.desc.d.ts.map
+//# sourceMappingURL=TBill.desc.d.ts.map

package/types/src/.generated/desc/lookupReference/GroupBy.desc.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=GroupBy.desc.d.ts.map

package/types/src/.generated/desc/lookupReference/PivotBy.desc.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=PivotBy.desc.d.ts.map

package/types/src/.generated/desc/statistical/{ETS.desc.d.ts → Ets.desc.d.ts}

@@ -1,4 +1,4 @@
 import { MinifiedDescriptors } from '@sheetxl/scripting';
 declare const descriptors: MinifiedDescriptors;
 export default descriptors;
-//# sourceMappingURL=ETS.desc.d.ts.map
+//# sourceMappingURL=Ets.desc.d.ts.map

package/types/src/.generated/desc/statistical/TTest.desc.d.ts

@@ -0,0 +1,4 @@
+import { MinifiedDescriptors } from '@sheetxl/scripting';
+declare const descriptors: MinifiedDescriptors;
+export default descriptors;
+//# sourceMappingURL=TTest.desc.d.ts.map

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

@@ -1,4 +1,4 @@
-import { Scalar } from '@sheetxl/primitives';
+import { Scalar, Omittable } from '@sheetxl/primitives';
 /**
  * Readers for arguments Excel declares `any` rather than `number`.
  *
@@ -23,10 +23,17 @@ import { Scalar } from '@sheetxl/primitives';
  * `parseAsSerialDate` supplies the refusal — `#VALUE!` for a boolean, whether it arrived as a
  * literal or as a cell, and an incoming error rethrown with its own identity.
  *
- * A blank CELL is serial 0. Excel answers `#N/A` for a genuinely empty SLOT (`EOMONTH(,0)`),
- * which we cannot yet distinguish — both reach the body as `null` (CALC-ISSUES item 43).
+ * A blank CELL is serial 0. A genuinely empty SLOT is `#N/A` in Excel (`EOMONTH(,0)`,
+ * `YEARFRAC(,39814)` — fn-battery financial/YEARFRAC, 2026-08-28); a parameter declared
+ * `Omittable<Scalar>` sees that slot as `undefined` and reads it through {@link anyDateRequired}.
  */
 export declare function anyDate(value: Scalar): number;
+/**
+ * A REQUIRED date parameter Excel declares `any` (`Omittable<Scalar>` on the declaration): an
+ * argument supplied EMPTY is a missing argument (#N/A); everything else reads through
+ * {@link anyDate}, so a blank CELL is still serial 0.
+ */
+export declare function anyDateRequired(value: Omittable<Scalar>): number;
 /**
  * Reads a plain NUMERIC argument declared `any` — the `months`/`basis` slots.
  *
@@ -35,4 +42,11 @@ export declare function anyDate(value: Scalar): number;
  * text parsed, boolean refused, error identity preserved.
  */
 export declare function anyNumber(value: Scalar): number;
+/**
+ * A REQUIRED parameter Excel declares `any` (`Omittable<Scalar>` on the declaration): an argument
+ * supplied EMPTY is a missing argument (#N/A) rather than a zero, and everything else reads
+ * through `anyNumber`. The `undefined` check must come first — `anyNumber` reads a blank cell's
+ * `null` as 0, which is what a blank CELL is measured to be.
+ */
+export declare function anyRequired(value: Omittable<Scalar>): number;
 //# sourceMappingURL=AnyArgs.d.ts.map

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

@@ -1,4 +1,34 @@
 type IterFn = (x: number) => number;
+/**
+ * The approximate yield a bond-yield iteration starts from: the annual coupon plus the pull to par
+ * spread over `years`, against a denominator that is the mid-point of par and the price less a
+ * `years`-scaled share of the same pull. At par it returns the coupon rate exactly, which is why
+ * a bond priced at 100 answers in one step.
+ *
+ * `years` is {@link getYearsToMaturity}, never the coupon count over the frequency. Measured on
+ * 1,154 rows of fn-battery financial/adhoc-yield-start, -n, -n2 and -n3 — bonds whose redemption
+ * dwarfs the price, where a hundred Newton steps carry the start out to a number that inverts.
+ *
+ * Used by: YIELD, ODDFYIELD.
+ */
+export declare function approximateYield(rate: number, pr: number, years: number): number;
+/**
+ * Excel's bond-yield iteration: Newton on the price with its ANALYTIC slope, at most a hundred
+ * steps from {@link approximateYield}, stopping the first time a step moves the yield by less than
+ * `1e-5` and answering the iterate the step just produced — so the answer is a PARTIALLY converged
+ * one, ~1e-10 from the root on an ordinary bond, and on a bond that cannot converge it is simply
+ * where the walk stood after a hundred steps.
+ *
+ * A slope that overflows to infinity, or a step that lands where the price cannot be evaluated
+ * (a `1 + y/f` at or below zero), is `NaN` — the caller's #NUM!.
+ *
+ * Measured on YIELD's 1,134-row battery and fn-battery financial/adhoc-yield-fingerprint,
+ * -start, -n, -n2, -n3, -domain (2026-09-09).
+ *
+ * Used by: YIELD, ODDFYIELD.
+ */
+export declare function solveYieldByNewton(start: number, priceFn: IterFn, slopeFn: IterFn): number;
+export {};
 /**
  * Solve `iterFn(x) = 0` numerically, starting from `guess`.
  *
@@ -14,6 +44,13 @@ type IterFn = (x: number) => number;
  *
  * Used by: YIELD, ODDFYIELD, ODDLYIELD.
  */
-export declare function solveByNewton(guess: number, iterFn: IterFn): number;
-export {};
+/**
+ * Bisection fallback when Newton-Raphson fails to converge.
+ *
+ * Phase 1: Expand a small bracket around guess until the function changes sign
+ *   (guarantees a root is bracketed, or gives up with NaN).
+ * Phase 2: Standard bisection to isolate the root.
+ *
+ * Returns NaN if no bracket is found within the iteration budget.
+ */
 //# sourceMappingURL=FinanaceSolver.d.ts.map

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

@@ -0,0 +1,23 @@
+import { Scalar, Omittable } from '@sheetxl/primitives';
+/** The arguments of AMORLINC/AMORDEGRC once read and validated. */
+export interface AmorArgs {
+    cost: number;
+    salvage: number;
+    /** The period as Excel indexes it: under 1 is period 1, above 1 truncates. */
+    periodIndex: number;
+    rate: number;
+    /** The stub period's day count (`getAmorDayCount`); its year fraction is `days / yearDays`. */
+    days: number;
+    yearDays: number;
+}
+/**
+ * The seven arguments of AMORLINC/AMORDEGRC — measured against Excel 16.0 (fn-battery
+ * financial/AMORLINC, /AMORDEGRC, 2026-08-28). Every one is Excel-declared `any`, so they are
+ * read here in declaration order, with the basis read AFTER the dates are validated (a reversed
+ * date pair beats a text basis: `…, DATE(2008,12,31), DATE(2008,8,19), …, "x")` is #NUM!). The
+ * serials truncate; the shared domain is `cost > 0`, `0 ≤ salvage ≤ cost`, `period ≥ 0`,
+ * `rate > 0`, both dates in the calendar and in order, and a truncated basis of 0, 1, 3 or 4.
+ * Returns `null` for #NUM!.
+ */
+export declare function amorArgs(cost: Omittable<Scalar>, datePurchased: Omittable<Scalar>, firstPeriod: Omittable<Scalar>, salvage: Omittable<Scalar>, period: Omittable<Scalar>, rate: Omittable<Scalar>, basis: Omittable<Scalar>): AmorArgs | null;
+//# sourceMappingURL=FinanceAmor.d.ts.map

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

@@ -0,0 +1,42 @@
+import { IRange } from '@sheetxl/primitives';
+/**
+ * The dated cash-flow operands of XNPV and XIRR, read the way Excel reads them (measured against
+ * Excel 16.0, fn-battery financial/XNPV, 2026-08-29).
+ *
+ * @remarks
+ * Both functions take two operands that are read TOGETHER, member by member, by flattened
+ * row-major ordinal — a 3x1 pairs fully with a 1x3 and a 2x2 pairs with a 4x1
+ * (DESIGN-RANGE-PAIRING). That makes the reading order a pair scan rather than a slot order, and
+ * it is one pass that stops at the first fault: a bad ordinal 2 is answered before ordinal 3's
+ * error is looked at.
+ *
+ * Ordinal 0 is not like the rest. Its DATE is read before its value (an error there wins over an
+ * error in the first flow) and range-checked before either, and a member of EITHER operand that
+ * is not a number is `#VALUE!` there where the same member at any later ordinal is `#NUM!` —
+ * so a whole operand of numeric text, or of blanks, answers `#VALUE!` while one number among
+ * them answers `#NUM!`.
+ */
+export interface DatedFlows {
+    /** The flow at each ordinal. */
+    values: number[];
+    /** Days from the first date, every serial truncated first. */
+    days: number[];
+}
+/**
+ * `(values, dates)` as XNPV and XIRR read them. `valuesSlot` is the argument index of the values
+ * operand (the dates operand is the next one), which is what tells a one-cell operand from a list
+ * of one; `dialect` picks between the two functions' member rules.
+ *
+ * The pair scan is common to both: a count mismatch is `#NUM!` before anything else, and then, per
+ * ordinal, an error in the values operand, an error in the dates operand, and only then the kinds
+ * and the date's own domain.
+ *
+ * What differs is what a member may BE. XNPV's list members must already be numbers — a text, a
+ * boolean, an empty string or a blank is `#VALUE!` at ordinal 0 and `#NUM!` after it — and its
+ * serials run `[1, MAX_SERIAL_DATE]` with every date at or after the first. XIRR COERCES its
+ * members instead (numeric text and date text parse, a boolean or a true text is `#VALUE!`
+ * wherever it sits), drops a pair whose VALUE is blank, answers `#NUM!` for a blank DATE beside a
+ * present value, admits serial 0, and does not order the dates at all.
+ */
+export declare function readDatedFlows(values: IRange, dates: IRange, valuesSlot: number, dialect?: 'xnpv' | 'xirr'): DatedFlows;
+//# sourceMappingURL=FinanceCashflow.d.ts.map

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