Skip to content

Delegate contract projection requirements to FinanceModels - #160

Closed
alecloudenback wants to merge 1 commit into
masterfrom
refactor/fm-owned-projection
Closed

alecloudenback wants to merge 1 commit into
masterfrom
refactor/fm-owned-projection

Conversation

@alecloudenback

@alecloudenback alecloudenback commented Sep 7, 2026 •

Copy link
Copy Markdown
Member

Merge map (updated 2026-09-29)

Part of the coordinated FinanceCore 2.8, FinanceModels 7.0, ActuaryUtilities 6.0 and MortalityTables 3.0 releases. Merge each stack bottom-up with Create a merge commit, delete each merged branch so GitHub retargets the next PR onto the default branch, and let the retargeted PR's CI finish before merging it.

Order Package PRs, merged left to right Then
1 FinanceCore #56 register 2.8.0
2 FinanceModels #311 → #314 → #295 → #308 → #315 → #316 → #317 → #318 → #319 → #320 → #322 → #323 → #324 → #325 → #326 register 7.0.0
3 ActuaryUtilities #160 → #161 (#160 is a draft, proposed to merge first with #161 rebased onto it; #161 merges after FinanceModels 7.0.0 is registered) register 6.0.0
any MortalityTables #136 → #137 → #138 → #139 → #140 → #141 → #142 → #143 → #144 → #145 → #146 → #147 → #149 → #151 → #148 (independent of the other three) register 3.0.0

This PR: ActuaryUtilities #160 (base the default branch). A draft, proposed to merge before #161.


AU's private _contract_keys traversal misses FinanceModels' transformed swap leg, so reprojection and contract sensitivities fail on a package-provided interest-rate swap. It also duplicates model-store construction in zspread.

Delegate reproject(contract, index_curve) to FinanceModels' Projection(contract; index) constructor and delete the private contract traversal. Add the explicit-model-store form reproject(contract, models) for distinct index curves, FX, and custom contracts. zspread now uses the same projection boundary and holds that projection fixed while solving the discount spread.

reproject consistently returns a Projection, including fixed contracts. Custom single-index contracts must declare their requirements in FinanceModels; explicit stores and valuation closures remain available for custom wiring.

Dependency / merge prerequisite:

  • Depends on Own contract projection model requirements in FinanceModels FinanceModels.jl#310 (tested at 9c5652efb6a21d072ce41b7f7efe18f00743c6c3).
  • Kept as a draft until that API is merged and released. Before merging AU, set Project.toml's FinanceModels lower bound to the actual release containing the API, then run the normal and downgrade CI. No unreleased version number is guessed, and ordinary CI against registered FinanceModels is expected to fail until this prerequisite is satisfied.

Validation:

  • Full AU suite passes on Julia 1.12.5 against the FM dependency commit (904 assertions), including Aqua.
  • 49 focused assertions pass on Julia 1.10.10 and 1.12.5 against that commit: swaps, forward-starting floaters, transformed legs, portfolios, explicit distinct index/FX stores, key-rate sensitivities versus explicit valuation closures, and nonzero z-spread round trips.
  • Runic formatting and git diff --check pass.

Addresses the AU side of shared review finding #3. Independent AU branch against master; no other AU review PR is required.

@alecloudenback

Copy link
Copy Markdown
Member Author

Heads-up for rebasing: #161 splits src/financial_math.jl into src/financial_math/{scalar_measures,key_rate_sensitivities,contract_sensitivities,scenario_sensitivities}.jl.

  • The _contract_keys/reproject hunks here now belong in src/financial_math/contract_sensitivities.jl.
  • zspread in that file also calls _contract_keys, so it needs the same FinanceModels-owned projection.
  • v6: unify sensitivities: shock coordinates, signed dollar risk, no tenor grids for parallel risk #161 also removes the contract forms that took a tenors argument (duration/dv01/convexity(target, curve, tenors)) in favor of (target, curve) and (target, forward, credit). Contract tests in test/projection_models.jl should use the no-tenor forms, except for KeyRates and sensitivities(target, curve, tenors), which keep their grid.

🤖 Generated with Claude Code

This was referenced Sep 30, 2026
alecloudenback added a commit that referenced this pull request Oct 1, 2026
Folds #160 into the v6 branch. The contract measures use
`FinanceModels.model_requirements` instead of AU's own `_contract_keys`
list, which missed the transformed floating leg of `InterestRateSwap`
(a `MethodError`) and treated an undeclared custom contract as needing
no projection.

With no requirements beyond the discount curve, the measures
differentiate `present_value(discount, contract)`, preserving custom
closed-form pricing; otherwise they rebuild the projection on the bumped
index curve. One helper, `_value`, replaces `_cvalue` and `_cvalue2`.

`reproject` is removed: it duplicated FinanceModels'
`Projection(contract; index)`. ActuaryUtilities 6 requires
FinanceModels 7.

Tests: #160's measure tests in the v6 call forms, a closed-form
contract, an undeclared contract, and a custom floater whose effective
and spread durations differ and match explicit valuation callbacks.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN
@alecloudenback

Copy link
Copy Markdown
Member Author

Folded into #161 as aff5836; closing in favor of it. #161 split financial_math.jl, so the change lives in src/financial_math/contract_sensitivities.jl there. It differs from this PR in three ways:

  • Contract measures use the projection requirements FinanceModels declares. With no requirements beyond the discount curve, they differentiate present_value(discount, contract), preserving custom closed-form pricing; otherwise they rebuild the projection on the bumped index curve.
  • reproject is removed in ActuaryUtilities 6 rather than extended. Use Projection(contract; index), or Projection(contract, models) for a model store.
  • ActuaryUtilities 6 requires FinanceModels 7.

This PR's measure tests are ported to the v6 call forms. #161 adds tests for a closed-form contract, an undeclared contract, and a custom floater whose effective and spread durations differ. The red CI here dates from 2026-09-07, before FinanceModels 6.5.0 released Projection(contract; index).

🤖 Generated with Claude Code

alecloudenback added a commit that referenced this pull request Oct 11, 2026
…nor grids for parallel risk (#161)

* Preserve sign in scalar DV01

* Unify curve convexity shock conventions

* Preserve position sign in scalar IR01 and CS01

* Consolidate sensitivity derivatives over named curve roles

* Remove trailing whitespace from moved docstrings

* Reuse sensitivity derivatives while preserving curve-role inference

* Specialize named-curve callbacks at the public entry point

* Record repeated sensitivity benchmarks against master

* Use LF line endings in benchmark comparison data

* Document and test convexity shock conventions with references

* Preserve zero-value dollar risk and validate scalar convexity tenors

* Define contract-bundle dollar risk at zero value; release as 6.0.0

`sensitivities(target, forward, credit, tenors)` derived `effective_dv01`,
`spread_dv01`, and `forward_dv01` as duration × value / 10_000, which is
NaN·0 for a zero-present-value position even though the exposure is finite
and `dv01(Effective()/Spread(), …)` already returns it. Compute the dollar
figures from the value gradient directly; the normalized durations and
key-rate vectors keep their documented undefined-at-zero behaviour.

Regression: a two-cashflow portfolio with zero present value and nonzero
DV01, both signs, single- and two-curve forms, plus a nonzero-value bond
to lock the unchanged path.

Bump to 6.0.0: scalar convexity for yield-model inputs changes its
numeric result, so the release is a major, not 5.12.0. Update the upgrade
guide header and the convexity guide accordingly.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014DUnw1ft1K357DbYdcuCCx

* Unify contract defaults and cashflow time handling

Default contract DV01 and convexity to Effective, honor embedded cashflow times across analytic sensitivities and derived grids, and share allocation-free fixed-cashflow convexity for yield models. Add regression coverage and migration documentation.

* Clarify sensitivity documentation and comments

* Measure parallel risk without tenor grids; unify IR01/CS01

Scalar IR01 and CS01 now equal the DV01 of the combined rate
base + spread, shocked in that rate's own coordinate. Per-component
bumping disagreed whenever the inputs mixed types (e.g. a curve base
with a scalar spread gave CS01 ≈ IR01 / (1 + spread)).

Tenor grids now appear only where results have a tenor dimension.
The scalar tenor-aware duration/DV01/IR01/CS01/convexity forms, their
callback and do-block variants, and the scalar contract forms never
depended on the grid, and their positions let swapped arguments
return wrong numbers silently. Remove them and add the missing
no-tenor equivalents: the DV01 do-block, two-curve callback IR01/CS01,
two-curve convexity blocks for callbacks and fixed cashflows, and
contract duration/DV01/convexity on (target, curve) and
(target, forward, credit). Every removed v5 call shape now throws.

Remove the finite-difference KeyRateZero/KeyRate/KeyRatePar API;
KeyRates applies the same bumps with exact derivatives.

Yield-model modified duration and DV01 for fixed cashflows use
analytic continuous-zero kernels; DV01 does not divide by value, so
zero-value exposure stays defined.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* Document shock coordinates and the v6 parallel-measure API

Add a canonical Shock coordinates section and restructure the
sensitivities guide around scalar measures, key-rate decomposition,
and contracts without tenor grids. Expand the v6 upgrade notes with
the liability DV01 sign, the IR01/CS01 identity, a migration table for
removed tenor forms, and the KeyRate* removal. Restore the historical
v5.6→v5.7 and v5.11→v5.12 notes to their original wording.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* Add market-input sensitivities for valuations that build their curves

sensitivities(valuation, inputs::NamedTuple) differentiates a valuation
with respect to named vectors of market inputs (quoted rates, spreads,
zero rates) and reports value plus per-input parallel and per-element
durations and signed DV01s. Inputs are bumped in the units they are
given, so quote conventions come from the caller's own constructors.
Up to 64 elements are differentiated in one forward pass, so a
valuation that refits a curve refits once.

Named curve and named input tuples dispatch separately; both require at
least one element. The named-curve form also reports per-tenor DV01s.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* Correct the market-input helper's evaluation count and DV01 wording

The helper evaluates the valuation once for the value and once more for the
derivatives (one forward pass per 64 inputs), so a valuation that fits a curve
fits it twice, not once. `-∂V/∂s / 10000` is the value lost for an increase,
not the value change. The duration and DV01 sums equal a parallel-shift
derivative only where the valuation is differentiable, which excludes
interpolation kinks such as a flat MonotoneConvex interval; link FinanceModels'
calibration sensitivities page for that contract.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* Converge spread and zspread on the Newton step, not the price residual

Both solvers accepted an absolute price residual below `tol`, so the answer
depended on the notional: a true 2% z-spread came back as 1.96% at a notional of
1e-10, and a zero market price could be accepted at the starting point. They now
stop once the (undamped) Newton step is below `tol` in rate units, which is
invariant to the cashflows' scale and defined at a zero price. `spread` keeps its
damped steps. Tests cover notionals 1e-12, 1 and 1e10 and a zero-price
mixed-sign stream; the upgrade guide notes the changed meaning of `tol`.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

* Verify repricing before accepting a spread; damp steps toward the domain edge

A small undamped Newton step does not by itself show that `spread` has converged: near a
combined annual rate of -100% the price derivative is so large that the step is tiny far
from the root (a base of -1 + 1e-13 returned 1e-13 instead of 1.05). A candidate is now
accepted only when the step is below `tol` and its pricing residual is within sqrt(eps)
of the gross discounted value under both curves, a scale that does not change with the
notional and is nonzero for zero-price and mixed-sign streams. Decisions use primal
values, so the returned candidate keeps its derivatives.

The fixed clamp at -0.999 is replaced by steps that go at most halfway to the edge of the
spread's domain: the spread must exceed -1, and so must the combined rate when a periodic
base is added nominally in its own convention. Spreads such as -0.49 on a -0.5 base and
-0.9999 on a zero base were unreachable before. A NaN valuation or derivative now throws
instead of being replaced by a fixed step.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Test that spread and zspread are scale-equivariant

Scaling every cashflow by k must scale values and dollar sensitivities by k and leave the
spreads unchanged. The three notional bugs found in recent reviews all broke this. The
new testset checks a coupon stream at notionals 1e-12, 1 and 1e10, both against the
unit-notional solve and against independent closed forms.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Remove checks that natural errors already cover; drop stale legacy docs

- `_ncurve_ad` no longer checks the derivative order, an empty set of curves, or curve
  types. The public signatures cannot reach those cases: they dispatch only on at least
  one yield model, so the natural `MethodError` fires first. `order` is an internal
  keyword that every caller passes as 1 or 2.
- `moic` no longer pre-checks for a distribution and a contribution. Without both, one
  of its sums has no terms and raises the same `ArgumentError` type. The docstring
  now says so.
- The zero-stream docs no longer mention legacy key-rate forms, which v6 removed.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Type zero cashflow streams like a nonempty result

Empty and all-zero streams still return exact zeros without valuing any payment:
linearity forces the value. Their numeric type is a convention, and it now matches the
type the same measure returns for a nonempty stream with the same amount, time and rate
or curve types. Before, the curve's type was left out, so a zero stream under a BigFloat
rate or curve returned Float64 while a nonempty one returned BigFloat, and Float32
amounts under a Float64 rate returned Float32 instead of Float64.

The rate or curve is queried once, at time zero, for that type. An untyped empty
collection (`Any[]`, `Cashflow[]`, `()`) therefore takes its type from the rate or curve
instead of an invented `Float64`. Each statistic builds its zero the way its nonempty
formula computes, including weight and divisor types and the Float64 shift that
callback derivatives use. Hull–White zero streams still skip simulation.

Tests compare empty, all-zero and nonempty result types for scalar measures,
present values and key rates across Float32, Float64, BigFloat and dual rates. The
zero-stream test curves now allow only the time-zero query. The docs and the v6 upgrade
guide describe the convention.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Decide spread damping on primal values so the solve stays differentiable

`copysign(max_step, newton)` converted a ForwardDiff Newton step to Float64
whenever the solve needed damping, so differentiating a spread near the domain
edge threw (spread(-0.5, y, [1.0], [1.0]) at y = -0.99, for example) although
the primal solve succeeds. The damping choice is discrete, so it now uses the
primal step; an undamped step and the accepted candidate keep their partials, and
the derivative is the implicit one at the root (1 with respect to the target and
-1 with respect to the base there). The same copysign path predates the
repricing check.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Type zero wrapped streams by their embedded times, as valuation does

A zero or empty stream's result takes the type a nonempty stream's would, but
its time type promoted the supplied times even for `Cashflow` elements, whose
valuation ignores them and uses the embedded times. A Float32 curve with Float32
amounts and embedded times gave Float32 durations, convexities and key-rate
bundles for a nonzero stream and Float64 for its zero or empty counterpart when
the supplied times were Float64. The zero-stream time now follows valuation:
the embedded time type for `Cashflow` elements (none for an abstract `Cashflow`
element type), and the supplied times otherwise.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Type abstract zero streams by the times their payments use

b45b9f6 typed a zero stream's time by dispatch on the element type, so a
`Cashflow[...]` collection (abstract element type) took `false` and ignored its
embedded times: with Float32 amounts at BigFloat times, a nonzero stream's
duration was BigFloat but the all-zero stream's Float32. `Any[...]` streams
likewise promoted the supplied times rather than the embedded ones. A
nonempty collection whose element type isn't concrete now promotes the times
its payments use (a `Cashflow`'s own, a number's supplied time), as
`_zero_amount` already scans the amounts present. Concrete and empty
collections keep the dispatch path.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Evaluate moic with empty sums of zero

`moic` relied on a sum over no terms to reject one-sign streams, but that error
is Julia's refusal to type an empty reduction, not an undefined quantity: it is
a MethodError on Julia 1.10 and an ArgumentError on 1.12, so the tests failed on
the minimum-version and Downgrade jobs. In the definition, a sum over no terms
is zero, and a total loss has a well-defined multiple of 0. Both sums now start
from `false`, which keeps the amounts' type: contributions only give 0.0, no
contributions give Inf (x/0), and an empty or all-zero stream gives NaN (0/0).
v5 threw an ArgumentError for these; the upgrade guide says so.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Describe moic's division by zero as undefined, not defined

The docstring said the ratio is "defined for any stream". A sum over no terms
contributes zero, which makes a total loss's multiple 0, but with no
contributions the ratio still divides by zero: Inf for positive distributions
and NaN when there are none, neither a meaningful multiple. The docstring and the
upgrade guide now say that; the behavior is unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Keep moic's sums type-stable

`init = false` made each accumulator a Union{Bool, Float64}. moic took 103 ns, against 31 ns for
AU 5. Both sums now start from `_zero_amount(cfs)`, which is the amounts' zero for a concrete
element type, and contributions are negated before summing. Negating the sum instead would turn an
empty sum into -0.0 and return -Inf when nothing was invested. The values are unchanged. moic now
takes 9 ns.

Tests: no contributions gives +Inf for floating-point amounts and for Cashflows. `Any[]` gives NaN.
The result is inferable for concrete element types.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Widen moic's contributions before negating them

30f4cf2 negated each contribution before summing, and so before `sum`
widens small integers: -typemin(Int8) wrapped, and
moic(Int8[-128, -1, 64]) was -0.504 instead of 64/129. The sum of the
negative amounts is now subtracted from the typed zero, which keeps the
widening, gives +0 when there are none (a ratio of +Inf), and keeps
Float32 amounts Float32. A single typemin contribution, already wrong
before 30f4cf2, is fixed too.

Found by the 2026-09-27 benchmark review.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Price each spread iterate once

spread of 360 cashflows took 22.6 µs, against 13.0 µs in 5.12. Each
Newton step priced the cashflows in Float64 and again with a dual number
for the derivative, although the dual evaluation already carries the
value, and the accepted candidate was discounted once for its residual
and again for its gross value.

- The residual and its derivative come from the one evaluation
  `ForwardDiff.derivative` makes (`_value_and_derivative`), which keeps
  any outer partials.
- The dual evaluation sums in another order, so the candidate's own step
  takes the residual from the Float64 valuation as before. Taking it from
  the dual value instead doubled the root's rounding error (mean 5e-17
  against 2.5e-17 over 300 random cases); with this step it is 2.2e-17.
- The candidate's residual and gross value come from one pass
  (`_primal_residual_and_gross`).

The acceptance tests are unchanged: a Newton step below `tol`, and a
residual within sqrt(eps) of the gross value, and every benchmark
spread is the same value as before. Now 13.0 µs for 360 cashflows
(5.12: 13.0) and 1.76 µs for 10 (2.25 µs before, 5.12: 1.70).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Normalize every key-rate result from one role-keyed shape

The shared engine `_ncurve_ad` keys derivatives by curve role
(`gradient.role`, `hessian.role.role`), but `_keyrate_ad` turned that
into two private schemas (`gradient`/`hessian` for one curve;
`base_gradient`, `credit_hessian`, `cross_hessian`, ... for two), the
two-curve `_keyrate_analytic` rebuilt the second, and each public method
normalized its own shape, with `_conv_blocks` for the two-curve blocks
and a third path for named curves.

Now both engines return `(; value, gradient, hessian, zero_stream)`
keyed by role. The analytic kernel still computes one gradient and
Hessian; `_role_keyed` exposes them under every role without copying.
The AD engine's `zero_stream` is always false: a zero callback value
does not identify a zero cashflow stream. `_keyrate` gives either
result for a callback or fixed cashflows, and the public methods
normalize only the blocks they return (`_relative`, `_per_bp`,
`_base_credit_cross`) and name them at the end, so each public array is
still new.

Every public key-rate, two-curve and named-role output (222 cases, with
zero and zero-net-value streams, Float32, BigFloat, outer duals, the
parallel forms and do-blocks) is identical to before, type included,
and every public method still infers (now tested). Allocations are
unchanged or lower (e.g. one-curve `sensitivities` 15 -> 8 allocations,
parallel two-curve `convexity` 11 -> 4).

From the 2026-09-27 structural review.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Delete the scalar fallbacks that no rate or curve can reach

v6 gave yield models their own analytic modified-duration and convexity methods and narrowed
the generic cashflow methods to `_YieldInput`. Every concrete input now dispatches to a
specific method: reals, periodic and continuous rates, `Yield.Constant` of a rate, and every
other yield model (`Frequency` has only the `Periodic` and `Continuous` subtypes). The
generic `duration(::Modified, ::_YieldInput, ::AbstractVector, times)` and
`convexity(::_YieldInput, ::AbstractVector, times)`, with their zero-stream branches and
callback paths, could no longer run. A malformed rate now gets a `MethodError`.

A snapshot of 1,660 public results (scalar measures over nine rates and curves and fifteen
input shapes, key rates, contracts, spreads, market inputs, Hull-White) is identical, types
included.

From the 2026-09-28 thermo review (F4).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Value each contract parallel shift once and reuse it in zspread

`_contract_parallel` valued the contract at a zero shift and then again with a dual number for
the derivative, although the dual evaluation already carries the value; `dv01` then discarded
that value, so every contract duration and DV01 reprojected and discounted twice (80 discount
calls instead of 40 for a 10-year bond). `duration` now takes both from one evaluation through
`_value_and_derivative`, `dv01` asks only for the derivative, and the wrapper is gone.

`zspread` rebuilt the Spread() valuation inline: its shifted discount curve and projection
dictionary are `_contract_parallel_value(Spread(), ...)` term for term. It now calls that
helper, and each Newton iterate is priced once, as `spread` already is.

Every value is bitwise unchanged: the 1,660-entry snapshot, and 600 random zspread results and
contract durations and DV01s (fixed and floating bonds, portfolios, one and two curves), are
identical, types included.

From the 2026-09-28 thermo review (F5).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Type zero-stream times from one table and share the payment scan

The zero-stream time rule was split between `_zero_stream_time`, which dispatched a `Cashflow`
element type on to a second family, `_zero_cashflow_time`, and that family's own `Union{}`
method could never run: `_zero_stream_time(::Type{Union{}}, times)` catches `Union{}` first.
`_zero_amount` and `_zero_stream_time` also each wrote out the scan that promotes the types of
the payments present in an abstractly typed collection.

The `Cashflow` methods now sit in the one `_zero_stream_time` table and `_scanned_zero` is the
shared scan. The `Cashflow{A, T}` method bounds both parameters as `Cashflow` does, and says why:
with an unbounded amount type Julia ranks `Type{<:Cashflow}` as more specific, and every
concrete `Cashflow` would silently take `false` (a first draft did exactly that for 11 of 99
probe cases).

Amount and time zeros are identical, values and types, over 99 combinations of typed,
abstract, empty, `Union{}`, tuple and dual streams and times, and the 1,660-entry snapshot is
unchanged.

From the 2026-09-28 thermo review (F7).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Default key-rate cashflow times instead of unwrapping Cashflow vectors

Thirteen key-rate, two-curve and named-curve methods had a twin for `AbstractVector{<:Cashflow}`
that split the collection into new amount and time vectors with `_extract_cfs_times`, although
the analytic kernel already reads each payment's embedded amount and time and types zero streams
by them. The primary cashflow methods now take `times = eachindex(cfs)`, and the twins and the
helper are gone. Wrapped streams give identical results, types included, across typed, abstract,
empty, all-zero, Float32 and BigFloat-time inputs (98 of 98 probe cases, and the 1,660-entry
snapshot), with fewer allocations: 1,312 B -> 176 B for a 60-payment `duration`, 1,600 B -> 496 B
for `sensitivities`.

Numeric amounts without times are now accepted and paid at periods 1:n, the default the scalar
measures already use.

The Hull-White cashflow forms take the same default. They are more specific than the yield-model
forms (`HullWhite <: AbstractYieldModel`), so `sensitivities(KeyRates(t), hw, cashflows)` without
times now simulates like the form with times. It used to fall through to the analytic
yield-model method and treat `hw` as a deterministic discount curve, which gave different
key-rate durations depending only on whether times were passed. A regression test covers both
the numeric and the wrapped form, and the upgrade guide describes the change.

Aqua finds no ambiguities.

From the 2026-09-28 thermo review (F3).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Differentiate curve bumps and market inputs with one named-role engine

The market-input `sensitivities(valuation, inputs)` flattened its named vectors, ran its own
`ForwardDiff.gradient!` with its own chunk setting, split the gradient by ranges and wrote out
the five result fields inline. `_ncurve_ad` was the same flatten-differentiate-split over
equal-length hat-bump blocks, and the named-curve callback bundle built the same five fields
through `_relative` and `_per_bp`; bitwise, it is the market-input bundle over zero bump
vectors. The contract bundle re-derived the normalizers inline as well.

`_named_ad(f, x)` is now the one engine: named vectors of any lengths, both derivative orders
through `_ad_derivatives`, the single-role case without views, the role-keyed result every
method normalizes. `_ncurve_ad` is the adapter that feeds it hat bumps, `_parallel_and_key_rate`
is the one formatter for the market-input and named-curve bundles, and the contract bundle uses
`_relative` and `_per_bp`. A one-input valuation now receives the input vector itself rather
than a view of it; the docstring says vectors.

One chunk policy, chosen by measurement (minimum of 20 samples; 360-payment PV valuations, a
ZeroRateCurve built from market inputs, Hull-White with 200 scenarios): gradients take up to
64 inputs per pass, which was never slower and up to 2x faster (30 tenors, one curve: 80.5 ->
39.9 us; 3 roles x 30: 277 -> 144 us; 70 inputs: 103 -> 65 us; Hull-White, 30 tenors: 1084 ->
647 us), while Hessians keep ForwardDiff's default, since wide chunks were up to 3x slower
there (2 roles x 30: 2.5 -> 8.4 ms; Hull-White, 30 tenors: 16.5 -> 33.4 ms). The market-input
form already used 64; order-one curve callbacks (named, contract and key-rate duration forms)
now do too.

The 1,660-entry snapshot and 14 wide-grid order-one bundles (up to 90 inputs, where the chunk
changed) are identical, types included, and every key-rate method still infers; the inference
testset now also covers market inputs, the contract bundle and omitted times.

From the 2026-09-28 thermo review (F1).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Pass every key-rate grid as a KeyRates marker

v6 already moved key-rate grids onto `KeyRates(tenors)` for duration, convexity and the one-,
two- and named-curve cashflow bundles, but three other conventions survived: the contract
bundles took a raw tenor vector last (`sensitivities(target, curve, tenors)`, also with
`forward, credit`), the layered contract form took it second
(`sensitivities(target, tenors; discount, index)`), and named-curve callbacks took it as a
keyword (`sensitivities(valuation, curves; tenors)`, plus a do-block twin). Meanwhile
`duration(Effective(), KeyRates(t), target, curve)` wrapped the vector form of the same call.

Every grid is now a `KeyRates` marker in the first position, as in the other key-rate methods:
`sensitivities(kr, target, curve)`, `sensitivities(kr, target, forward, credit)`,
`sensitivities(kr, target; discount, index)`, `sensitivities(kr, valuation, curves)` and its
do-block forwarder `sensitivities(vf, kr, curves)`. The five raw-vector and keyword forms are
removed and join the "removed call shapes throw" test; the contract key-rate durations route
through the new bundle. The two named-curve result shapes are unchanged. Results are identical
(the 1,660-entry snapshot, run with the new signatures, matches the old one exactly).

`sensitivities(kr, contract, hw)` was ambiguous between the contract bundle and the Hull-White
scenario callback. It values the contract on the model's discount function, as
`duration(kr, contract, hw)` already did, and a test pins the two together.

The upgrade guide maps each removed call to its replacement; the grid is validated where
`KeyRates` is built, and a grid mutated afterwards is still caught where it is used (now tested
for the named-curve and contract bundles too).

Decided by the maintainer (option A) after the 2026-09-28 thermo review (F2).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Dispatch the spread floor on periodic compounding

`_spread_floor(::Rate)` checked `base.compounding isa Periodic` at run time and returned the
default floor otherwise. A method for `Rate{<:Any, Periodic}` says the same thing through
dispatch, and every other rate reaches the existing `-1.0` fallback. Floors are identical for
reals, periodic rates of several frequencies and signs, continuous rates and yield models, and
the spread tests pass unchanged.

From the 2026-09-28 thermo review.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Split scalar_measures.jl by responsibility

The 786-line `scalar_measures.jl` held five things: the measure markers and `KeyRates` grid that
every other file dispatches on, the cashflow valuation utilities (`present_values`, `price`,
`breakeven`, `moic`), the scalar duration and convexity measures, the `spread` solver, and AD
helpers now shared with contract risk. They now live in `measures.jl` (included first),
`valuation.jl`, `scalar_measures.jl` and `spread.jl`, and `derivatives.jl` holds the AD helpers
together: `_primal` and `_value_and_derivative` from the spread section, and `_ad_derivatives`
and the `_named_ad` engine from the key-rate file. `cashflow_risk.jl`, which only FinancialMath
includes, moves into `financial_math/`.

This is a definitions-only move: apart from five section headers and the include list, the
source lines are the same multiset as before, docstrings stay attached, the 1,660-entry snapshot
is identical and Aqua finds no ambiguities.

From the 2026-09-28 thermo review (F6).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Keep the named-role engine inferable on Julia 1.10

`_named_ad` let its gradient-view and Hessian-block closures capture `result`, whose type
depends on the derivative order. Julia 1.12 still inferred every public method, but 1.10 lost
the result type, and nine forms in the "key-rate results are inferred" testset (every callback
key-rate method, the named-curve and market-input bundles and the contract bundle) returned an
abstract `NamedTuple` there. The closures now capture the concretely typed value, gradient and
Hessian, as `_ncurve_ad` did before it became an adapter, and the testset passes on 1.10 and 1.12.
Results are unchanged (the 1,660-entry snapshot is identical).

Fixes a regression from "Differentiate curve bumps and market inputs with one named-role engine".

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Normalize the contract bundle behind a function barrier

A floating-rate bond's projected value is not inferred, so in the contract bundle every
normalizer call on the engine result was a dynamic dispatch, and the keyword calls behind
`_relative` cost more than the inline arithmetic they replaced: the floater bundle on six
tenors went from 32.4 to 35.8 us (minimum of five alternating fresh-process runs). The
normalization now happens in `_contract_bundle(r)`, dispatched once on the concrete result, as
the key-rate and market-input bundles already do; the same bundle takes 26 us, the cost of the
engine alone. Inferred contracts (fixed bonds) are unaffected, and results are unchanged
(1,660-entry snapshot identical).

Fixes a regression from "Differentiate curve bumps and market inputs with one named-role engine".

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Show where rate and credit sensitivities differ in the two-curve docs

The two-curve section stated that fixed cashflows have equal IR01 and
CS01, then gave a floater without saying why its measures split, in code
that read curves as callables with Float64 conversions; the key-rate
section rebuilt the same floater as a longer loop and labeled its summed
modified durations "IR01" and "CS01".

- The equal-sensitivity rule is a note: a valuation that depends only on
  the combined rate has equal IR01, CS01 and combined-curve DV01, and equal
  convexity blocks; the fixed-cashflow forms are always in this case.
- One floater, written with `discount(b, t - 1, t)` and `discount(b + c, t)`,
  sits beside the fixed cashflows, with IR01/CS01 side by side, why the
  floater's IR01 is small (its rate risk runs to the next reset), a bar
  chart, and a link to the contract-based effective vs spread durations.
- The key-rate example reuses that floater and labels its vectors as the
  base and credit key rate durations, which sum to the parallel modified
  durations.

Docs build clean (the new figure takes Documenter's PNG fallback, as the
risk-measures figure does).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Clarify two-curve risk conventions and cross convexity

* Let FinanceModels declare what contract measures project

Folds #160 into the v6 branch. The contract measures use
`FinanceModels.model_requirements` instead of AU's own `_contract_keys`
list, which missed the transformed floating leg of `InterestRateSwap`
(a `MethodError`) and treated an undeclared custom contract as needing
no projection.

With no requirements beyond the discount curve, the measures
differentiate `present_value(discount, contract)`, preserving custom
closed-form pricing; otherwise they rebuild the projection on the bumped
index curve. One helper, `_value`, replaces `_cvalue` and `_cvalue2`.

`reproject` is removed: it duplicated FinanceModels'
`Projection(contract; index)`. ActuaryUtilities 6 requires
FinanceModels 7.

Tests: #160's measure tests in the v6 call forms, a closed-form
contract, an undeclared contract, and a custom floater whose effective
and spread durations differ and match explicit valuation callbacks.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Document and test AD and finite-bump par quote risk

* Value contracts in FinanceModels valuation contexts

Contract measures differentiate `present_value(Models(discount; index), target)`:
the bumped discount curve discounts and prices, and every model a contract reads
by key is the bumped index curve. FinanceModels 7 removed `model_requirements`
and `Projection(c; index)`, and FinanceCore 3 values a collection of contracts as
the sum of its contracts, so the closed-form branch and the vector method go.

A `Composite` of closed forms, or of a closed form and a fixed bond, now has
risk; custom contracts are written against the context. FinanceCore 3 is
required.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Use one hat rule and one parallel shift; select the two-curve role by marker

`_hat_bump` reads the interval and weights from `_active_hats`, and a yield
model's parallel shift is the one-knot `_PARALLEL_GRID` bump, so the scalar
callback, contract and two-curve forms shift curves through the same
constructor (discount factors and hat values are bitwise unchanged). The
scalar ForwardDiff path for single-shift callbacks and contracts stays.

IR01 and CS01 select their curve role with `_role`, so each two-curve form is
one method.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Take the valuation callback first in every callback form

Every callback measure is now `measure(f, markers..., curves or inputs)`:
`duration(f, curve)`, `duration(f, DV01(), curve)`, `duration(f, IR01(), base,
credit)`, `convexity(f, kr, curve)`, `sensitivities(f, kr, curves)`, as
`sensitivities(f, inputs)` already was. Do-block syntax therefore works for
every input type, including scalar and `Rate` inputs.

The 18 reverse-order forwarders and the three ambiguity patches (two `invoke`s
and the Hull-White contract disambiguator) are deleted: a marker or grid now
sits where a callback cannot, and contract forms keep `(marker, target, curve)`.
`Test.detect_ambiguities` reports none. The untyped callback slot no longer
catches contracts, so `duration(DV01(), kr, bond, curve)`, `dv01(kr, bond,
curve)` and `convexity(kr, bond, curve)` return effective key-rate risk instead
of calling the bond.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Measure fixed cashflows through one shock-coordinate kernel

`_coordinate(y)` restates the docs' shock-coordinate table: the convexity
weight t(t + 1/m), with 1/m = 0 for continuous coordinates and yield models,
and the divisor 1 + y/m. Macaulay, modified duration, DV01 and convexity for
fixed cashflows are each one method on `_weighted_sums`/`_weighted_ratio`, for
scalars, `Rate`s and yield models alike. The per-type methods, including the
identity `Yield.Constant{<:Rate}` overloads, the automatic-differentiation route
for scalar and `Rate` DV01, `_macaulay_ratio` and `_zero_shifted` are deleted.
`_weighted_sums` checks payment times once, before the zero-stream shortcut and
its `@inbounds` loop.

Macaulay, modified duration and convexity are bitwise unchanged, values and
types (2,850 comparisons over rates, curves and streams, zero streams and
errors included). DV01 for scalar and `Rate` inputs moves by at most 4 ulp in
Float64 and is now computed at the rate's precision, so a Float32 rate gives a
Float32 DV01.

Vector methods default `times = eachindex(cfs)`, as the key-rate forms do,
instead of materializing `timepoint.(cfs, 1:n)`; one collecting method per
arity handles tuples, generators and arrays of other shapes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Request Hull-White simulation with Scenarios; a bare HullWhite is a curve

`Scenarios(hw; n_scenarios, timestep, horizon = nothing, rng)` asks for
simulated paths, and is not a yield model. `sensitivities(f, kr, s)` passes
the paths to `f`, and `sensitivities(kr, s, cfs, times)` values fixed cashflows
as their mean present value, with today's bodies: one seed drawn per call and
reused in every AD evaluation, zero streams valued on `hw.curve` without
simulating or touching the RNG, and the horizon defaults of 30 years for
callbacks and one year past the last payment for cashflows. Results are
bitwise unchanged.

A bare `HullWhite` now means its discount function to every measure, so
`sensitivities(kr, hw, cfs, times)` agrees with `duration(kr, hw, cfs, times)`
instead of returning a Monte Carlo estimate under the same name. The four
duplicated keyword lists go. The bumped model is rebuilt with
`ConstructionBase.setproperties(hw; curve)` rather than positionally.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Take wasserstein quantile gaps in the accumulator's float type

The three exact transport kernels (equal-size samples, unequal-size samples,
finite atoms) computed `abs(x - y)` in the samples' own type, so integer samples
wrapped around: `wasserstein(UInt8[0], UInt8[1])` was 255 and
`wasserstein(Int8[-100], Int8[100])` was 56. One helper, `_gap`, converts both
values to the accumulator's type before subtracting. Tests check the examples,
symmetry, and that UInt8, Int8, Int64 and Float64 versions of the same samples
and discrete laws give identical distances for p in {1, 2, Inf}.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Attach the two-curve IR01/CS01 docstring to duration, not _role

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Return a lone or end hat's bump without weighting it

Routing the parallel shift through the hat rule cost `duration(Effective(),
floater, curve)` about 7%: every discount factor evaluated the one-knot grid's
range endpoints and weighted the bump. A one-knot grid's hat is flat, so
`_hat_bump` returns the bump directly, as it does beyond the end knots. Hat
values and shifted discount factors are bitwise those of the former
`_hat_bump` and `TenorShift(curve, (z, t) -> Continuous(shift) + z)`, including
infinite and nested-dual bumps, and the Effective benchmark is back at parity.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Bump a Hull-White model's curve and keep its closed forms

duration(Effective(), cap, hw), its Composite and key-rate forms threw a
MethodError: the bump layered a TenorShift over the model, so the cap and
swaption kernels no longer received a HullWhite. A bump now moves hw.curve
and keeps the model, with its mean reversion and volatility, as Scenarios
already did. Discount factors are the bumped curve's either way.

The tests value real caps and swaptions against the same measures on
HullWhite(a, σ, bumped curve). Swaption convexity throws, because
FinanceModels differentiates the critical rate to first order only.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Subtract integer samples exactly before rounding the wasserstein gap

Converting both endpoints to Float64 first rounded typemax(Int64) - 1 and
typemax(Int64) to the same float, so their distance was 0.0 instead of 1.0
for p = 1, 2 and Inf, and likewise for UInt64. One integer type now subtracts
in its wider type, larger minus smaller; two different integer types, whose
mixed arithmetic wraps around, subtract as BigInt. The difference is rounded
once.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Measure one role with the single-curve engine

The two-curve IR01/CS01 callbacks and the contract key-rate Effective and
Spread durations differentiated both curve roles and kept one. They now
bump only the curve their measure moves, through the single-curve DV01 and
key-rate forms. Values agree to rounding (Spread and fixed contracts are
bitwise equal; floaters differ by at most 9e-16).

The Hull-White key-rate test compared the bundle with the expression it
was defined as; it now compares two separate calculations with ≈. New
tests compare the contract key-rate Effective and Spread durations with
the bundle fields.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Let Scenarios bump Hull-White through the engine

`_bumped` already moves a Hull-White model's curve and keeps the model, so
`Scenarios` passes `s.model` to the engine instead of bumping `s.model.curve`
and swapping it back in itself. Zero streams are valued on `s.model`, whose
discount factors are its curve's. The 30-year callback default is written
once, and `_cashflow_times` is deleted: FinanceCore pairs amounts with times
only up to the shorter collection, so only the bounds check matters.

Results and the RNG state after each call are bitwise unchanged for every
form, horizon and time input checked.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Deduplicate tests and move shared fixtures

- Delete the scalar IR01/CS01 sign block in key_rate_durations.jl; the
  combined-rate testset in parallel_measures.jl covers it, and now also
  checks CS01 with Cashflow objects and with omitted times.
- Delete the three-curve analytic-vs-AD test in key_rate_durations.jl, which
  repeated the one in sensitivities.jl. Its public-API checks move there,
  and that test reads the engine result by field, not by position.
- Merge the two spread/zspread notional testsets in audit.jl.
- Drop the ambiguity check in callable_valuations.jl; Aqua runs it.
- Move CashflowValue, ScenarioValue, _same_sensitivity and
  ZeroCashflowTestCurve into sensitivity_fixtures.jl, so no test file
  depends on another's definitions. analytic_types.jl uses
  ZeroCashflowTestCurve instead of an identical EmptyCashflowTestCurve.
- Test the key-rate hat shape through `duration(KeyRates(1:10), ...)` for
  single payments instead of calling the private `_hat_bump`.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Move the curve shifts into their own file

The hat functions, `_bumped`, `_PARALLEL_GRID` and both `_parallel_bumped`
methods serve the scalar callbacks, the contract measures and `Scenarios`,
not only key rates. They move with `AYM` and `HW` into curve_shifts.jl,
included after measures.jl, so scalar_measures.jl can write `AYM` and the
two `_parallel_bumped` methods sit together. The definitions only move.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Merge the fixed-cashflow IR01 and CS01 methods

Fixed-cashflow IR01 and CS01 are one rule: the DV01 of `base + credit`.
The scalar form is now one `Union{IR01, CS01}` method, and the key-rate
cashflow form computes `duration(DV01(), kr, base + credit, cfs, times)`
instead of taking one role of the two-role kernel; it matches the old
result to a relative 3e-16. The two near-duplicate docstrings become one,
which also documents the key-rate forms and states which operand's
compounding a `Rate` sum takes. `_role` has no caller left and is deleted.

The callback docstring now describes only the callback forms.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Delete dead code

- `_cashflow_vector(::AbstractArray{Union{}})` existed because an empty
  `Union{}[]` also matched a `Cashflow` method. No method dispatches on
  `AbstractVector{<:Cashflow}` any more, and the zero-stream type table
  already handles `Union{}`; `()`, `Union{}[]` and `Any[]` give the same
  zeros and types without it.
- `dv01` forwarded keywords, but no `duration` method takes any since the
  Hull-White keywords moved into `Scenarios`. A keyword call still raises a
  `MethodError`.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Reject a discount layer named index

The contract `discount=` form merges the projection curve into the named
curves as `index`, so a discount layer named `index` was silently replaced:
the projection curve was summed twice and the value was wrong. A layer with
that name now throws an `ArgumentError`, and the docstring says so.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Tighten docstrings and comments

Code comments and docstrings, checked against the code:
- Recompute the stale `julia-repl` outputs (convexity, callback duration,
  `spread`) and replace the `convexity` examples, which were mostly
  `duration` calls, with two `convexity` calls.
- IR01/CS01 marker docstrings: no contract method takes them, and
  fixed-cashflow key-rate IR01 and CS01 are equal; only the callback forms
  separate them. Say "credit curve" throughout.
- A floater's effective duration is small, not the time to its next reset
  (that holds once the current coupon is fixed, see `locked_floater`), and
  its spread duration is close to a fixed-rate bond's, not its maturity.
- Modified duration is per unit of rate, and DV01 is the value lost.
- Use ≈ where a parallel result is a reordered sum of key-rate results.
- State the `spread` repricing test and domain bound as the code checks
  them, and give `spread` and `zspread` their full signatures.
- Shorten the zero-stream caveats to a link; say plainly that callback and
  contract forms do not use the zero-stream convention.
- `breakeven` returns the time from which the balance stays nonnegative.
- Scope the `_gap` comment: only two `Signed`/`Unsigned` integers subtract
  exactly; `Bool` and integer-float pairs convert first.
- Clarify the shock-coordinate, parallel-grid and contract-context
  comments.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Tighten docs and fix inaccurate claims

Docs pages, README and landing page, each claim checked against the code:
- A new floater's effective duration is small, not the time to its next
  reset, and its spread duration is close to a fixed-rate bond's, not its
  maturity (0.19 and 4.60 years for the 5-year example).
- The multi-curve example labelled relative durations as IR01/CS01; it now
  shows the dollar risk per role. Discount layers are not basis spreads.
- A bare HullWhite keeps its closed forms; it is not valued only on its
  discount function. `Scenarios` already reuses one seed per call.
- State the domains the code has: linear-interpolation input risk equals
  the key-rate decomposition only inside the knot range; knot bumps match a
  hat at the knots; a portfolio of self-timed contracts sharing a reporting
  currency is worth ≈ the sum of its parts. Use ≈ for reordered sums.
- Upgrade guide: drop the "new" parallel forms v5 already had and the
  internal-only bullets; say convexity changed for yield models; state
  what changed for unmarked contract DV01 and convexity, and list only v5
  calls that existed; describe the KeyRateZero migration, integer
  wasserstein gaps and the spread convergence test as the code does them.
- Quickstart values round correctly (105.66, 10.63); the README `discount`
  example takes a time; the argument-order tip matches callback-first.
- Move the floater key-rate example next to the two-curve key-rate forms
  and drop the separate section; shorten repeated IR01 = CS01 and
  zero-stream explanations to one statement and links; consistent terms
  (credit curve, normalized, key-rate, Hull–White, AD, V for value).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Pass only the paid times to FinanceCore in simulated valuation

FinanceCore 3 now throws when amounts and times differ in length, so the
unused trailing times of a shared grid, which ActuaryUtilities accepts, are
left out before the per-path present value.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Return zspread's spread as a Continuous rate

`zspread(...).zspread` is now `Continuous(s)`, as `spread` returns a
`Periodic` rate, and `zspread_dv01` stays a number. A number added to a
curve is read as an annual rate, so `credit + result.zspread` mispriced a
5-year bond by 2.2e-4 per unit of face; the typed spread reprices. `s0` may
be a number, read as continuously compounded, or a `Rate`.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Say what adding a Periodic rate to a continuous one does

`z + Periodic(0.01, 1)` adds log(1.01) in z's continuous convention; it is
not +100 bp annual effective. The example now shows both.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Rename the date duration to policy_duration

duration(issue_date, date) shared a name with interest-rate duration.
It is now policy_duration(issue_date, date), with the same results.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Remove price, the Duration supertype and unused imports

price was abs(present_value(...)), and nothing dispatched on Duration.
Statistics was an unused dependency, and OptimalTransport imported
StatsBase without using it. FinancialMath now owns duration, since
policy_duration took the other method.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Remove the fixed-cashflow forms that repeat one result per curve

Cashflows discounted at base + credit, or at a product of named discount
layers, have the same derivatives with respect to every layer. The IR01
and CS01 cashflow forms, the two-curve and named cashflow forms of
convexity and sensitivities, and _role_keyed returned that one result
several times. The combined curve gives it once. The IR01 and CS01
callback forms remain for valuations in which the curves differ.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Pair cashflow amounts and times through one input boundary

Every fixed-cashflow kernel now takes its inputs from _cashflow_inputs.
It resolves omitted times to the amounts' indices before any reindexing,
reuses 1-based vectors, collects tuples and generators once, views offset
vectors from 1, and trims unused trailing times with a view. Amounts and
times therefore pair by position, as in FinanceCore. Offset times used to
pair by index, and offset key-rate grids read out of bounds inside
@inbounds loops; KeyRates now keeps a 1-based copy of its tenors.

Key-rate and Scenarios cashflow forms accept tuples and generators like
the scalar forms. present_values, breakeven and spread use the same
boundary.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Share the Newton iteration between spread and zspread

_newton holds the loop: one value-and-derivative evaluation per step, an
exact-root exit, and the iteration limit. Each solver passes its own step
rule, so spread keeps its damping, its domain protection and its
repricing check scaled by gross value, and zspread keeps its continuous
coordinate and step-size acceptance. Results and messages are unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Select derivative order with markers and put the curve before the contract

sensitivities now returns (; value, duration, dv01), or with SecondOrder()
also convexity. FirstOrder() is the default. value is always a number;
the derivative fields are numbers for parallel shifts, vectors and
matrices with KeyRates, and keyed by role with several curves. One
normalizer builds every result from the total value and dollar
derivatives. Without KeyRates each role takes one parallel shock, so no
tenor gradient is built and summed, and FirstOrder takes no second
derivatives. The DV01() forms of sensitivities are removed.

Contract measures take the curve first and the index curve as a keyword,
as in Models(discount; index). Contract sensitivities report the
discount and index roles; effective convexity is the sum of all four
blocks, and convexity(Spread(), ...) is new. zspread takes
(discount, contract, price; index). A vector of Cashflows after a curve
is fixed cashflows, and other contract vectors are portfolios.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Let dv01 take the valuation first

dv01(valuation, args...) forwards to duration(valuation, DV01(), args...)
for a rate or curve, a KeyRates grid, two curves and named curves, so
callable structs and do-blocks work as they do for duration. With
several curves, duration(valuation, DV01(), ...) returns one DV01 per
role, the dv01 field of sensitivities.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Fix the Scenarios horizon, grid and seed at construction

Scenarios now requires horizon, which must be a whole number of
timesteps up to rounding. It validates the grid with
FinanceModels.simulation_steps, the function simulate counts steps with,
before drawing a seed, and stores the step count and the seed. An
unaligned horizon throws ArgumentError instead of silently reaching the
next grid point. Every valuation simulates the same paths from the
stored seed and never touches the caller's RNG, so results are
reproducible and add across positions with different maturities.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Check that every yield reaches the analytic measures

The dispatch test compared the selected method with a signature that no
method has, so it always passed. It now checks that every yield type
selects the same analytic duration and convexity methods, and that their
results are the closed forms summed in payment order, to the bit.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Document the v6 call shapes and sensitivities results

Add a cheat sheet of call shapes to the upgrade guide and reconcile its v6
notes with the curve-first contract forms, the order markers and the
Scenarios horizon. Update the sensitivities page, the financial math
page, the overview and the README.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Drop Scenarios' unused step count

Scenarios stored the validated step count, but nothing read it: simulate counts the steps
from the same horizon and timestep with the same function. The tests now check the grid by
its effect, a payment at the horizon valued and one a step later throwing.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Pay a Cashflow at its own time in present_values

present_values discounted each entry over its paired time and added Cashflow objects to the
accumulator, so a Cashflow at time 2 paired with time 10 was worth 74.08 instead of 94.18, and
Cashflows at different times threw. Each payment is now read through its amount and resolved
time, and the entries are numbers of the type the zero-stream rule gives.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Read named market inputs by position

A single offset input reached ForwardDiff with its offset axis, since `reduce(vcat, ...)` returns
a lone vector as it is, and ForwardDiff rejected it. Every input is now viewed from 1 before it is
concatenated: the valuation receives 1-based vectors of the same lengths, and the derivatives are
1-based. Ordinary vectors are unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Key two-curve convexity by role, as sensitivities does

convexity(valuation, [KeyRates(t),] base, credit) returned (; base, credit, cross), while the
convexity field of sensitivities(valuation, SecondOrder(), ...) nests by role. Both now return
(; base = (; base, credit), credit = (; base, credit)) from one normalizer, without building the
durations and DV01s. With KeyRates, credit.base is the transpose of base.credit.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Remove dv01; duration(DV01(), ...) is the one standalone DV01

dv01 repeated duration(DV01(), ...) and duration(valuation, DV01(), ...), and held the contract
calculations itself. Those now live in duration(DV01(), Effective() | Spread(), [KeyRates(t),]
discount, contract; index), and the fixed-cashflow and key-rate routers send contracts there.
Markers come in the order DV01(), then Effective() or Spread(), then KeyRates. Every
sensitivities result keeps its dv01 field. The upgrade guide maps each removed call.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Add dollar convexity, the raw second derivative

DollarConvexity() selects H = ∂²V/∂sᵢ∂sⱼ in the usual shock coordinates, with no factor of
one-half and no basis-point scaling, for fixed cashflows (also scalars and Rates), callbacks on one
or two curves, and contracts (Effective() by default, or Spread()), with or without KeyRates, in
the layouts of convexity. Second-order sensitivities return the same Hessian as dollar_convexity,
also for named curves, market inputs and Scenarios; first-order results are unchanged. It is
defined at zero value and adds across positions: cashflows [-1, 1] at [0, 1] under a 0% continuous
rate are worth zero, with DV01 0.0001 and dollar convexity 1.

The analytic kernels and the AD engine already computed the Hessian, so it is returned without
another derivative evaluation or division by value. Normalized parallel convexity now divides the
raw second derivative by the value instead of differentiating abs(value); the values are the same.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Nw2FiivhYrC16532c1mJQN

* Raise ConstructionBase floor for FinanceModels 7 dependencies

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant