QUA-1256: author E22 cap-strip proof contract

LIMITATIONS.md

@@ -69,7 +69,8 @@ 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, T102, and E22 repairs, that baseline contains 586 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, T102, and E22 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` |
+| L68 | **E22 cap-strip Monte Carlo is a forward-marginal proof** — the authored USD cap has twenty quarterly unadjusted periods, explicit fixing and payment dates, ACT/360 accrual, ACT/365 option time, ACT/ACT ISDA curve time, named OIS/SOFR-3M/Black-vol inputs, and seeded antithetic sampling. Both lanes value the same sum of individual caplet expectations | The 0.5% analytical-reference comparison supports this bounded proof. The Monte Carlo helper and its typed lowering use independent forward marginals, not a short-rate path or a joint forward-rate process. Ordinary route admission restricts these capabilities to the existing Black cap/floor helper profile and blocks incompatible product/state/process/path/reducer/measure or calibration combinations. Its legacy n_steps, mean_reversion and sigma arguments are ignored; E22 cannot declare those controls. The proof does not establish calibration, shifted/normal volatility, seasoned fixing or production holiday support | `TASKS_PROOF_LEGACY.yaml`, `trellis/models/rate_cap_floor.py`, `trellis/agent/task_manifest_validation.py`, `trellis/agent/executor.py`, `trellis/agent/family_lowering_ir.py`, `trellis/agent/route_registry.py`, `tests/test_tasks/test_e22_cap_strip.py`, `docs/quant/pricing_stack.rst` |
 | 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

@@ -2400,17 +2400,112 @@ tasks:
     analytical: black_scholes
   status: pending
 - id: E22
-  title: 'Cap/floor: Black caplet stack vs MC rate simulation'
+  title: 'Cap strip: Black caplets vs sampled forward marginals'
+  description: >-
+    Price the authored USD cap strip under the named rates scenario. Compare
+    discounted Black-76 caplets with seeded antithetic Monte Carlo of independent
+    lognormal caplet forward marginals, reporting holder present value in USD.
+  task_disposition: executable_pricing
+  instrument_type: period_rate_option_strip
+  market_scenario_id: usd_rates_smile
+  validation_policy: invariants_and_cross_method
   construct:
   - analytical
   - monte_carlo
   new_component: null
-  market:
-    source: mock
-    as_of: 2024-11-15
-    discount_curve: usd_ois
-    forecast_curve: USD-SOFR-3M
-    vol_surface: usd_rates_smile
+  benchmark_contract:
+    product: period_rate_option_strip
+    cap_floor: cap
+    currency: USD
+    notional: 1000000.0
+    strike: 0.04
+    valuation_date: '2024-11-15'
+    start_date: '2025-02-15'
+    end_date: '2030-02-15'
+    payment_frequency: quarterly
+    day_count: ACT/360
+    model_time_day_count: ACT/365
+    discount_curve_day_count: ACT/ACT ISDA
+    forecast_curve_day_count: ACT/ACT ISDA
+    calendar_name: weekend_only
+    business_day_adjustment: unadjusted
+    fixing_rule: accrual_start
+    payment_rule: accrual_end
+    fixing_lag_days: 0
+    payment_lag_days: 0
+    accrual_dates:
+    - '2025-02-15'
+    - '2025-05-15'
+    - '2025-08-15'
+    - '2025-11-15'
+    - '2026-02-15'
+    - '2026-05-15'
+    - '2026-08-15'
+    - '2026-11-15'
+    - '2027-02-15'
+    - '2027-05-15'
+    - '2027-08-15'
+    - '2027-11-15'
+    - '2028-02-15'
+    - '2028-05-15'
+    - '2028-08-15'
+    - '2028-11-15'
+    - '2029-02-15'
+    - '2029-05-15'
+    - '2029-08-15'
+    - '2029-11-15'
+    - '2030-02-15'
+    fixing_dates:
+    - '2025-02-15'
+    - '2025-05-15'
+    - '2025-08-15'
+    - '2025-11-15'
+    - '2026-02-15'
+    - '2026-05-15'
+    - '2026-08-15'
+    - '2026-11-15'
+    - '2027-02-15'
+    - '2027-05-15'
+    - '2027-08-15'
+    - '2027-11-15'
+    - '2028-02-15'
+    - '2028-05-15'
+    - '2028-08-15'
+    - '2028-11-15'
+    - '2029-02-15'
+    - '2029-05-15'
+    - '2029-08-15'
+    - '2029-11-15'
+    payment_dates:
+    - '2025-05-15'
+    - '2025-08-15'
+    - '2025-11-15'
+    - '2026-02-15'
+    - '2026-05-15'
+    - '2026-08-15'
+    - '2026-11-15'
+    - '2027-02-15'
+    - '2027-05-15'
+    - '2027-08-15'
+    - '2027-11-15'
+    - '2028-02-15'
+    - '2028-05-15'
+    - '2028-08-15'
+    - '2028-11-15'
+    - '2029-02-15'
+    - '2029-05-15'
+    - '2029-08-15'
+    - '2029-11-15'
+    - '2030-02-15'
+    rate_index: USD-SOFR-3M
+    model: black
+    mc_distribution: independent_lognormal_forward_marginals
+    sampling: antithetic
+    n_paths: 100000
+    seed: 42
+    valuation_measure: holder_present_value
+    output_unit: currency_amount
+    output_currency: USD
   market_assertions:
     requires:
     - discount_curve
@@ -2422,8 +2517,42 @@ tasks:
       vol_surface: usd_rates_smile
   cross_validate:
     internal:
-    - mc_rate_cap
-    analytical: black76_cap
+    - analytical
+    - monte_carlo
+    reference_target: analytical
+    relations:
+      monte_carlo: within_tolerance
+    tolerance_pct: 0.5
+    tolerance_unit: percent_of_reference_price
+    output_unit: currency_amount
+    output_currency: USD
+    target_contracts:
+      analytical:
+        method: analytical
+        route_family: analytical
+        backend_binding_id: trellis.models.rate_cap_floor.price_rate_cap_floor_strip_analytical
+        validation_bundle_id: analytical:cap
+        payoff_family: period_rate_option_strip
+        exercise_style: none
+        model_family: interest_rate
+        observation_style: fixed_schedule
+        variant_parameters:
+          model: black
+      monte_carlo:
+        method: monte_carlo
+        route_family: monte_carlo
+        backend_binding_id: trellis.models.rate_cap_floor.price_rate_cap_floor_strip_monte_carlo
+        validation_bundle_id: monte_carlo:cap
+        payoff_family: period_rate_option_strip
+        exercise_style: none
+        model_family: interest_rate
+        observation_style: fixed_schedule
+        variant_parameters:
+          distribution: independent_lognormal_forward_marginals
+          sampling: antithetic
+        spec_overrides:
+          n_paths: 100000
+          seed: 42
   status: pending
 - id: E23
   title: 'European equity call under local vol: PDE vs MC'

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: 586
+issue_digest: fe69e77b4f3804741c12d59f384608ec4fd5861ce507640902e763b46e6b7f4c
+task_fingerprint: 5c556d9a0f00b65ffbcc405aef606c35ab95f0a0c3ad243035d31d2542e2ffaf
 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

@@ -155,7 +155,7 @@ remain outside executable pricing selection.
 | `T125` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | Swing option: dynamic programming on tree vs LSM MC |
 | `T126` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | Spread option (Kirk approximation) vs 2D MC vs 2D FFT |
 | `E21` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | European equity call: 5-way (tree, PDE, MC, FFT, COS) |
-| `E22` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | Cap/floor: Black caplet stack vs MC rate simulation |
+| `E22` | `executable_pricing` | `TASKS_PROOF_LEGACY.yaml` | Authored Black caplets versus seeded lognormal forward marginals |
 | `E23` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | European equity call under local vol: PDE vs MC |
 | `E24` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | Merton jump-diffusion call: MC vs FFT |
 | `E25` | `proof_only_hold` | `TASKS_PROOF_LEGACY.yaml` | FX option (EURUSD): GK analytical vs MC |

doc/plan/active__task-manifest-integrity.md

@@ -37,7 +37,7 @@ exact capability blocker before Trellis can synthesize economic inputs.
 | 10.1 | `QUA-1255` | Done | T02/T17 receive authored callable pricing fixtures |
 | 10.2 | `QUA-1258` | Blocked | T82/T89 receive explicit callable analytics outputs |
 | 10.3 | `QUA-1254` | Backlog | T73 receives an authored European swaption contract |
-| 10.4 | `QUA-1256` | Backlog | E22 receives an authored cap-strip contract |
+| 10.4 | `QUA-1256` | In Progress | E22 receives an authored cap-strip contract |
 | 10.5 | `QUA-1257` | Done | T102 receives an authored terminal-basket contract |
 | 10.6 | `QUA-1259` | Blocked | Remove the repaired title-derived pricing bootstraps |
 | 11 | `QUA-1251` | Blocked | Reusable variable-coupon callable-bond primitive |