QUA-1258: author callable duration comparison

LIMITATIONS.md

@@ -69,7 +69,7 @@ ground truth until revalidated.
 |---|-----------|--------|-------|
 | L49 | **Agent-cycle and institutional approval evidence are governed internal review surfaces, not external model certification** — Trellis now exposes a stable `agent_cycle` result surface for quant/critic/arbiter/model-validator evidence, model-promotion eligibility, and benchmark trigger rates, and `policy_bundle.production.institutional` can require approval, model-review, snapshot, run-artifact, and audit-bundle evidence before production execution, but these surfaces only certify recorded internal governance evidence for the run or model version | Product and desk review surfaces can show why a cycle passed, failed, was unavailable, or lacked required institutional approval artifacts, but they must not be read as external model approval, regulatory sign-off, xVA/FpML coverage, or correctness beyond the recorded validation scope | `trellis/agent/cycle_surface.py`, `trellis/agent/task_runtime.py`, `trellis/platform/models.py`, `trellis/platform/policies.py`, `trellis/platform/services/pricing_service.py`, `docs/developer/audit_and_observability.rst`, `docs/developer/hosting_and_configuration.rst`, `docs/user_guide/pricing.rst` |
 | L57 | **Typed comparison-target coherence exposes rather than fills missing numerical composition** — Explicit targets carry canonical method, route/binding, variant, validation, and semantic identities, and the runtime rejects partial explicit target sets, ambiguous references, missing declarations, and unbound shared artifacts before pricing. Explicit semantic axes are now projected onto the per-target `ProductIR` before route selection, which prevents serialized target prose from reclassifying terminal spread baskets and lets T102/T126 bind their independent Stulz, Kirk, Monte Carlo, and Hurd-Zhou lanes. T102 now proves its Monte Carlo variant through authored `n_paths`, `n_steps`, `seed`, and `mc_method` spec overrides while its Stulz reference binds the raw analytical kernel. Other variant execution still must be proven by spec overrides or a canonical full-contract executable declaration; sparse legacy targets still rely on visibly inferred contracts, and `T13` remains an exact-bucket semantic-guard canary whose cached analytical artifact cannot honestly represent both theta-PDE variants and the analytical reference | Coherence can select and prove reusable numerical composition when it exists, but it deliberately does not invent missing methods, infer undeclared semantics for sparse legacy targets, or let one cached artifact impersonate several variants | `trellis/agent/comparison_target_contracts.py`, `trellis/agent/assembly_tools.py`, `trellis/agent/task_runtime.py`, `trellis/agent/executor.py`, `TASKS_PROOF_LEGACY.yaml`, `docs/developer/task_and_eval_loops.rst`, `docs/quant/pricing_stack.rst` |
-| L64 | **Legacy proof-task contracts remain broadly incomplete** — the task-manifest gate now validates all modern corpus envelopes strictly and freezes the legacy corpus's exact field-level debt and normalized task content behind a checked baseline. After the authored T02, T17, and T102 repairs, that baseline contains 590 exact issue identities across 122 incomplete retained rows; those rows still lack one or more authored descriptions, economic contracts, market contracts, acceptance criteria, or explicit execution/hold dispositions. Product-specific field sufficiency remains owned by the semantic validators and repair tickets | New or worsened structural manifest debt fails the corpus gate, and the main task runner plus specific-id rerunner reject selected incomplete legacy rows before default market construction or code generation. The exact authored T02, T17, and T102 rows pass that boundary without weakening the remaining debt. The legacy baseline is only a migration guard; it must not be interpreted as evidence that title-only rows are priceable, that every specialized proof harness is governed by the main runner boundary, or that every structurally valid modern product contract is semantically complete | `TASKS_PROOF_LEGACY.yaml`, `TASKS_PROOF_LEGACY_BASELINE.yaml`, `trellis/agent/task_manifest_validation.py`, `scripts/validate_task_manifests.py`, `scripts/run_tasks.py`, `scripts/rerun_ids.py`, `doc/plan/active__task-manifest-integrity.md` |
+| L64 | **Legacy proof-task contracts remain broadly incomplete** — the task-manifest gate now validates all modern corpus envelopes strictly and freezes the legacy corpus's exact field-level debt and normalized task content behind a checked baseline. After the authored T02, T17, T89, and T102 repairs, that baseline contains 585 exact issue identities across 121 incomplete retained rows; those rows still lack one or more authored descriptions, economic contracts, market contracts, acceptance criteria, or explicit execution/hold dispositions. Product-specific field sufficiency remains owned by the semantic validators and repair tickets | New or worsened structural manifest debt fails the corpus gate, and the main task runner plus specific-id rerunner reject selected incomplete legacy rows before default market construction or code generation. The exact authored T02, T17, T89, and T102 rows pass that boundary without weakening the remaining debt. T89 is only a same-payoff Hull-White duration identity at constant zero OAS, not independent validation or market-price OAS calibration. The legacy baseline is only a migration guard; it must not be interpreted as evidence that title-only rows are priceable, that every specialized proof harness is governed by the main runner boundary, or that every structurally valid modern product contract is semantically complete | `TASKS_PROOF_LEGACY.yaml`, `TASKS_PROOF_LEGACY_BASELINE.yaml`, `trellis/agent/task_manifest_validation.py`, `scripts/validate_task_manifests.py`, `scripts/run_tasks.py`, `scripts/rerun_ids.py`, `doc/plan/active__task-manifest-integrity.md` |
 | L65 | **Callable-bond coupons are scalar fixed-rate only** — the checked callable-bond cashflow, compiler, lattice, and PDE routes accept one scalar coupon rate rather than a dated variable-coupon schedule. Legacy task T09 asks for a step-up callable bond but does not author the coupon rates or effective dates, so its validated task contract now fails closed with an exact `variable_coupon_schedule` blocker and zero build attempts instead of using the old title-derived flat 5% fixture | Trellis can price the bounded fixed-coupon callable-bond cohort, but it cannot reasonably price step-up, step-down, floating, or otherwise variable-coupon callable bonds. T09 remains an expected honest block until QUA-1251 adds a reusable dated coupon primitive and an explicit schedule | `trellis/models/short_rate_fixed_income.py`, `trellis/instruments/callable_bond.py`, `trellis/models/callable_bond_pde.py`, `trellis/execution/compiler.py`, `trellis/agent/task_runtime.py`, `TASKS_PROOF_LEGACY.yaml`, `tests/test_agent/test_task_runtime.py` |
 | L66 | **Physical Bermudan swaption lattice support is a bounded one-factor, static-basis composition** — the strict route preserves explicit co-terminal swap tails, separate named discount/forecast curves, complete supported leg conventions, a provenance-complete named constant-parameter Hull-White set, and authored uniform-grid controls. It supports physical settlement, simple floating coupons with a deterministic additive forward basis, and ACT/365F model time. Stochastic basis, reset/payment convexity, compounded overnight coupons, amortizing or scheduled notionals, seasoned or pre-started fixed tails requiring accrued-settlement treatment, ACT/ACT ICMA coupon accrual without explicit quasi-coupon reference periods, parameterized day-of-month rolls, non-shipped calendar aliases, cash/annuity settlement, term-structured model volatility, multi-factor rates, native Greeks, and production convergence/error governance remain unsupported | Trellis can reasonably price the checked bounded physical dual-curve contract only when each adjusted first fixed accrual start is on or after exercise; it must fail closed rather than value a whole already-started fixed coupon, reinterpret richer Bermudan swaptions through the legacy T04 helper, use a European/Black fallback, or approximate a convention mapping. P005 is the exact executable evidence: its strict lattice lane prices and remains visible even though the paired Monte Carlo lane honestly blocks | `trellis/models/rate_swap_tail.py`, `trellis/models/hull_white_parameters.py`, `trellis/agent/semantic_contracts.py`, `trellis/agent/executor.py`, `trellis/agent/knowledge/canonical/routes.yaml`, `TASKS_EXTENSION.yaml`, `tests/test_models/test_rate_swap_tail.py`, `tests/test_agent/test_physical_bermudan_swaption_semantics.py`, `tests/test_tasks/test_p005_physical_bermudan_swaption.py`, `docs/quant/lattice_algebra.rst`, `docs/user_guide/pricing.rst` |
 | L58 | **FpML normalization is bounded to fixed-float IRS, physical European swaption, and scheduled cap/floor cohorts** — Support-contract version 1.0.0 distinguishes secure inspection, economic normalization, executable structural lowering, and paired conformance. `make_fpml_request(...)` and `trellis.io.fpml` securely inspect inline UTF-8 FpML 5.13 confirmation `dataDocument` payloads and normalize one regular, single-currency, constant-notional fixed-float swap into `StaticLegContractIR`, one physically settled European payer/receiver swaption into `ContractIR` with the complete swap nested under `underlying_contract`, or one regular single-currency constant-strike cap/floor into the existing signed `PeriodRateOptionStripLeg`. Swaptions reuse the structural resolved Black-76 declaration; cap/floors reuse the existing static strip declaration; historical settled premiums are reported separately and excluded from contract identity. `TASKS_FPML_CONFORMANCE.yaml` pairs all three admitted cohorts with independently specified native contracts and proves identity, projection, structural selection, market binding, price, and non-economic envelope invariance; its negative cohort certifies exact honest blockers with zero agent calls. This evidence does not widen support. Trellis still does not perform complete XSD validation, support other views/versions, resolve external references, bind imported seasoned coupons to historical fixing histories, classify vendor extension children, or normalize amortizing, compounding, stubbed, end-of-month or clamped high-day, cross-currency, OIS, inflation, lifecycle, package, cash-settled/Bermudan/American/partial/automatic/straddle swaption, unsettled-premium, cap/floor collar, stepped-strike, averaged, geared/spread, early-terminable, or other product forms | An admitted swap, physical European swaption, or scheduled cap/floor strip can price deterministically through shared structural execution when the caller declares a valuation party and valuation date and all cohort constraints hold. Unclassified extension children and all other FpML economics remain fail-closed with exact import, clarification, conflict, or unsupported-feature blockers; this is not general FpML pricing coverage | `TASKS_FPML_CONFORMANCE.yaml`, `trellis/io/fpml/`, `trellis/agent/fpml_conformance.py`, `trellis/agent/contract_ir.py`, `trellis/agent/static_leg_contract.py`, `trellis/agent/imported_documents.py`, `trellis/agent/platform_requests.py`, `trellis/platform/executor.py`, `docs/developer/fpml_support_matrix.rst`, `docs/developer/fpml_import.rst`, `docs/quant/contract_ir.rst`, `docs/quant/static_leg_contract_ir.rst`, `doc/plan/draft__fpml-interoperability-roadmap.md` |

TASKS_PROOF_LEGACY.yaml

@@ -1611,15 +1611,68 @@ tasks:
     analytical: attribution_identity
   status: pending
 - id: T89
-  title: OAS duration (spread duration) for callable bonds
-  construct: analytics
+  title: 'Callable effective duration: constant-zero-OAS same-payoff identity'
+  description: >-
+    Compare OASDuration with no market-price anchor and Duration on the named
+    USD fixed-coupon callable-bond proof fixture using the same Hull-White
+    tree. Hold OAS at zero and use symmetric 25 bp parallel discount-zero-rate
+    shifts, with current callable holder PV as denominator. Require effective
+    duration in years under the authored relative-duration tolerance; this is
+    a same-payoff same-model identity, not an independent oracle.
+  task_disposition: named_proof_fixture
+  proof_fixture_id: usd_fixed_coupon_callable_bond_5pct_2025_2035_v1
+  market_scenario_id: usd_callable_fixed_5pct_proof
+  validation_policy: invariants_and_cross_method
+  construct: lattice
   new_component: oas_duration
   cross_validate:
     internal:
     - oas_bump_duration
-    - modified_duration
-    external:
-    - quantlib
+    - same_payoff_parallel_duration
+    reference_target: same_payoff_parallel_duration
+    relations: {oas_bump_duration: within_tolerance}
+    tolerance_pct: 0.000001
+    tolerance_unit: percent_of_reference_price
+    output_unit: currency_amount
+    output_currency: USD
+    output_tolerances_pct: {effective_duration: 0.000001}
+    analytics_contract:
+      profile: callable_same_payoff_duration_v1
+      output_name: effective_duration
+      output_unit: years
+      tolerance_unit: percent_of_reference_duration
+      bump_bps: 25.0
+      market_price: null
+      constant_oas_bps: 0.0
+      risk_coordinate: parallel_continuously_compounded_discount_zero_rate
+      shock_convention: symmetric_up_down
+      denominator: 2_times_bump_decimal_times_current_callable_holder_pv
+      derivative_method: finite_difference
+      forward_policy: rederive_default_preserve_named_forecast_curves
+      model_policy: preserve_parameters_recalibrate_tree
+      reference_role: same_payoff_same_model_identity_not_independent_oracle
+      measures:
+        oas_bump_duration: OASDuration
+        same_payoff_parallel_duration: Duration
+    target_contracts:
+      oas_bump_duration: &t89_same_callable_hw_target
+        method: rate_tree
+        route_id: exercise_lattice
+        route_family: rate_lattice
+        backend_binding_id: trellis.models.trees.algebra.price_on_lattice
+        variant_parameters:
+          lattice_model: hull_white
+          model_parameter_set: callable_fixed_5pct_proof:hull_white
+          mean_reversion: 0.1
+          sigma: 0.01
+          tree_steps: 200
+        validation_bundle_id: rate_tree:callable_bond
+        payoff_family: callable_fixed_income
+        exercise_style: issuer_call
+        model_family: interest_rate
+        observation_style: exercise_schedule
+        equivalence_group: t89_same_callable_hull_white_payoff
+      same_payoff_parallel_duration: *t89_same_callable_hw_target
   status: pending
 - id: T90
   title: 'Vega surface: per-expiry per-strike vega bucketing'

TASKS_PROOF_LEGACY_BASELINE.yaml

@@ -1,8 +1,8 @@
 version: 1
 manifest: TASKS_PROOF_LEGACY.yaml
-issue_count: 590
-issue_digest: 454a9b098b6d8de5754b9e151004670d2b33c667155ca8eea2bc928b5705acd6
-task_fingerprint: 55b9bcdd3364c0e1c0ca6d96f3cc9caf17e7cf4a78a40af92541804e0c368876
+issue_count: 585
+issue_digest: 819df8b48dc63330687fa7657ecc92a22720c7df7674f1305d1a34f5e8f14b9c
+task_fingerprint: 8b09f608fec66515f832a3b60fb66b9a435caaa68bd427fe0b411f50c52af04d
 policy: exact_issue_identity_and_task_content
 note: >-
   This baseline freezes known contract incompleteness in the retained legacy

doc/plan/active__legacy-task-migration-map.md

@@ -22,6 +22,11 @@ effective dates, while the checked callable-bond routes accept only one scalar
 fixed coupon. `QUA-1251` owns the missing variable-coupon primitive and an
 authored T09 schedule.
 
+`QUA-1258` authors `T89` on the same named fixed-coupon fixture as T02/T17.
+It requires constant-zero-OAS effective duration and the same-payoff parallel
+duration reference in years at symmetric 25 bp shocks. This internal identity
+does not claim an independent oracle or market-price OAS calibration.
+
 T03, T83, and T85 no longer cite resolved limitations as blockers. Their
 manifest dispositions now match this map: T03 is a `research_hold` pending
 a reproducible lattice experiment, T83 is a `proof_hold` pending an authored
@@ -119,7 +124,7 @@ remain outside executable pricing selection.
 | `T86` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | Theta (time decay) for options via tree and PDE |
 | `T87` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | Rho (rate sensitivity) for equity options |
 | `T88` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | Book P&L attribution: rate + spread + vol decomposition |
-| `T89` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | OAS duration (spread duration) for callable bonds |
+| `T89` | `named_proof_fixture` | `TASKS_PROOF_LEGACY.yaml` | Callable effective duration: constant-zero-OAS same-payoff identity |
 | `T90` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | Vega surface: per-expiry per-strike vega bucketing |
 | `T94` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | FX market bridge: Garman-Kohlhagen vs MC with explicit domestic/foreign curve selection |
 | `T95` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | xVA framework: CVA + DVA + FVA on IR swap portfolio |

docs/developer/task_and_eval_loops.rst

@@ -856,7 +856,7 @@ payoff, schedule, strike/coupon terms, or settlement rule. Those bridge
 decisions are task-runner contracts, not general natural-language parser
 behavior.
 
-Legacy ``T02`` and ``T17`` are executable only through the named
+Legacy ``T02``, ``T17``, and ``T89`` are executable only through the named
 ``usd_fixed_coupon_callable_bond_5pct_2025_2035_v1`` proof fixture and
 ``usd_callable_fixed_5pct_proof`` market scenario. Manifest loading hydrates
 the complete economic contract before provenance is recorded; the fixture
@@ -868,6 +868,24 @@ targets, and records per-target acceptance. The product-specific validator
 rejects altered fields, missing units, changed references, or relaxed controls
 as ``legacy.callable_bond_invalid_contract``.
 
+``T89`` retains holder-PV price reporting in USD and declares its required
+``effective_duration`` output separately in ``cross_validate.analytics_contract``.
+The two pricing targets explicitly share the same Hull-White execution identity;
+their analytics are ``OASDuration(None, 25bp)`` and ``Duration(25bp)``, not different
+pricing models. The internal task-analytics bridge executes those public
+measures over the bound payoff and validates finite non-boolean values, years,
+successful status, the current-price denominator, the 25 bp shock and resolved
+finite-difference provenance before extracting scalars. Per-output units and
+provenance survive in ``output_metadata`` and target ``output_acceptance``.
+Existing ``output_tolerances_pct`` performs the relative-duration comparison.
+Missing, failed, non-finite, misunitized, or mismatched duration fails the task
+even when both holder prices agree; no external oracle is claimed.
+Direct ``run_task`` calls recognize the reserved, whitespace-normalized ``T89``
+ID independently of mutable corpus/manifest labels and validate its exact
+contract before market construction or build attempts. Contradictory task kinds
+cannot redirect T89 through the early FpML dispatcher; ordinary FpML conformance
+requests retain their existing dispatch behavior.
+
 ``T09`` follows the same fail-closed boundary for a different reason. Its title
 requests a step-up issuer-callable bond but the retained row does not author
 the dated coupon rates or effective dates, and the checked callable-bond