Source: https://guthlabs.ai/docs/instruments/bond-duration-convexity/mechanism/

instrument mechanism / verified-clean

# Bond Duration & Convexity mechanism

The inspectable method record for Bond Duration & Convexity, kept separate from implementation and qualification.

Status: **VERIFIED_CLEAN**Lifecycle: **verified-clean**

## Model scope

The core formulas are standard under explicit discrete-coupon assumptions, but the specification is ambiguous about coupon frequency, yield compounding convention, time units, PV calculation, and the exact price-change formula. Verdict is NEEDS_REVIEW until those conventions are made explicit. The educational-only and linear/quadratic-approximation label is appropriate, but it should also state that the result is not option-adjusted and that the approximation is local.

- The stated formulas are standard only when t is measured in coupon periods and y is the yield per coupon period; the output labels duration in years without specifying coupon frequency or the required conversion.

- The present-value definition is omitted. Price must be defined as Price = Σ CF_t/(1+y)^t, with cash-flow timing specified.

- The estimated price-change formula is not stated. The standard second-order approximation is ΔP ≈ P[-ModD·Δy + 0.5·Convexity·(Δy)^2], where Δy is a decimal yield change consistent with the duration and convexity conventions.

- For periodic bonds, modified duration and convexity must be converted consistently when the user enters a nominal annual yield. For m coupon periods per year, annual-yield modified duration is typically D_year/(1+y_nominal/m), while annual-yield convexity requires the appropriate 1/m^2 conversion from period convexity.

- The convexity formula shown is the standard discrete-coupon formula, but its units are squared coupon periods unless t and y are explicitly defined on an annual-period basis.

## Units and conventions

- Vectors 1, 2, and 4 assume annual coupons, annual effective yield, t in years, cash flows per 100 face value, and yield changes entered as decimal values.

- Vector 3 assumes semiannual coupons, a nominal annual yield of 6% compounded semiannually, per-period yield y=0.06/2=0.03, and conversion of period-based duration and convexity to nominal-annual-yield sensitivity.

- Price change per 1% means a +0.01 absolute yield change, not a 1% relative change in the yield.

- Cash flows are assumed to occur exactly at integer coupon periods, with no accrued interest, day-count adjustment, or settlement-date interpolation.

## Inspectable vector

One of 4 source-bound review vectors:

````
{
  "inputs": {
    "face_value": 100,
    "cash_flows": {
      "t=1": 0,
      "t=2": 100
    },
    "yield": 0.05,
    "yield_change": 0.01,
    "coupon_frequency": 1
  },
  "expected_outputs": {
    "price": 90.702947846,
    "macaulay_duration_years": 2,
    "modified_duration_years": 1.904761905,
    "convexity_years_squared": 5.442176871,
    "estimated_price_change_for_plus_1_percent_yield": -1.702994
  },
  "working": "PV1 = 0/(1.05)^1 = 0. PV2 = 100/(1.05)^2 = 100/1.1025 = 90.702947846. Price = 0 + 90.702947846 = 90.702947846. Macaulay D = [1·0 + 2·90.702947846]/90.702947846 = 2 years. Modified D = 2/1.05 = 1.904761905 years. Convexity = [1·2·0 + 2·3·90.702947846]/[90.702947846·(1.05)^2] = 6/1.1025 = 5.442176871 years². Relative estimated change = -(1.904761905)(0.01) + 0.5(5.442176871)(0.01)^2 = -0.01904761905 + 0.0002721088436 = -0.01877551020. Price change = 90.702947846·(-0.01877551020) = -1.702994 approximately. This is an edge case: zero coupon cash flows before maturity."
}
````

## Failure boundary

**BREAK_CLAIMED** · SELF_FLAGGED

The input y=-1 makes every discounting denominator vanish, so the instrument must reject it. A further convention hazard exists because untyped values such as 5 and 1 can be interpreted either as decimal rates or as percentages.

## Other records

[01**Overview**](<https://guthlabs.ai/docs/instruments/bond-duration-convexity/>)[03**Implementation**](<https://guthlabs.ai/docs/instruments/bond-duration-convexity/implementation/>)[04**Qualification**](<https://guthlabs.ai/docs/instruments/bond-duration-convexity/qualification/>)

## Sources and evidence

These pointers bind the page to evidence. They do not grant authority or collapse verification into deployment.

- `VERIFIED_LEDGER.json`

- `evidence-tranche6/tranche6-results.json`

- `BOUNDARY_HAZARD_CATALOG.json`