docs: reconcile documentation with current implementation

.codex/artifacts/specs/repository-documentation-reconciliation.md

@@ -0,0 +1,150 @@
+# Repository Documentation Reconciliation - Specification
+
+## Source
+
+- User request: repository-wide documentation review and update, approved 2026-07-15.
+- Baseline: merged `master` at `1589089bdf10df352ce5cf9cde963fd6b51a4f95`.
+- Published-document set: `.github/scripts/check_docs.py` (`DOCS`, 33 Markdown files).
+- Prior audit: `.codex/artifacts/reviews/codebase-documentation-audit.md` at commit `7b959542`.
+- Latest capability references: `docs/methodology/xccy_calibration.md`,
+  `docs/methodology/yield_curve_jacobian.md`, and public C++/Python/Excel surfaces.
+
+## Problem Statement
+
+DAL's automated documentation checker passes, but it verifies structural integrity rather
+than full agreement with the current implementation. Since the prior repository audit,
+substantial numerical, runtime, packaging, curve, and XCCY work has landed. Most detailed
+documentation is current, but several public claims, architecture flows, API spellings,
+surface-availability statements, example listings, and indexes are incomplete or stale.
+
+The repository needs a source-backed audit of every published Markdown file, followed by
+focused edits that describe the current library without turning overview pages into copies
+of the methodology documents.
+
+## Goals
+
+- Audit all 33 Markdown files selected by `.github/scripts/check_docs.py` against the
+  current implementation.
+- Revalidate every still-relevant finding in the 2026-07-10 codebase documentation audit.
+- Correct inaccurate API names, quantitative claims, runtime ownership descriptions,
+  architecture flows, build commands, and cross-surface availability statements.
+- Make major current capabilities discoverable from the root and documentation indexes.
+- Record one auditable disposition for every published document: changed, verified current,
+  or intentionally unchanged with evidence.
+- Publish the reconciliation as a documentation-only follow-up pull request from `master`.
+
+## Non-Goals
+
+- No C++, Python, Excel, web, CMake, workflow, or generated-file behavior changes.
+- No attempt to add the missing Excel worksheet getter for the joint XCCY effective inverse;
+  document the current surface accurately instead.
+- No hand edits under `dal-cpp/dal/auto/` or `dal-excel/auto/`.
+- No edits to `CLAUDE.md`, `.claude/`, `AGENTS.md`, third-party documentation, build output,
+  or Codex skill instructions.
+- No speculative API promises, migration roadmap, or implementation history in current-state
+  documentation. Historical context remains in `CHANGELOG.md`.
+- No wholesale prose rewrite when a document is already accurate.
+
+## Functional Requirements
+
+- **FR1 - Complete published-document inventory:** Derive the audit set from the `DOCS`
+  expression in `.github/scripts/check_docs.py`, not from an independently maintained list.
+  The review artifact shall contain exactly one disposition for each selected document.
+- **FR2 - Source-backed ground truth:** Validate claims against the closest authoritative
+  source: public headers for C++, pybind11 and `dal/api.py` for Python, handwritten plus
+  generated registrations for Excel, FastAPI/React source for web, CMake/presets/scripts for
+  build instructions, and tests/examples/benchmarks for observable workflows.
+- **FR3 - Prior-audit reconciliation:** Recheck the findings in
+  `.codex/artifacts/reviews/codebase-documentation-audit.md` against current `master`. Current
+  docs shall not repeat limitations that have been fixed or omit material constraints that
+  remain.
+- **FR4 - Root and index discoverability:** Keep `README.md` concise while adding links for
+  major current capabilities that are otherwise absent, including cross-currency pricing and
+  calibration. Correct the `docs/README.md` heading hierarchy and remove its obsolete claim
+  that analytic Jacobians are exclusive to `LOG_DISCOUNT`.
+- **FR5 - Architecture accuracy:** `docs/architecture.md` shall describe immutable
+  operation-level `MarketFixingSnapshot_` ownership separately from the mutable process-wide
+  fixing store. Its calibration flow shall distinguish generic single/staged calibration,
+  staged XCCY basis calibration, and simultaneous domestic/foreign/basis XCCY calibration.
+- **FR6 - Exact API spelling and availability:** Developer-facing identifiers shall match
+  compilable or callable surface names. In particular, C++ notional-mode constants shall use
+  `XccyNotionalMode_::Value_::*`. Documentation shall distinguish core/public staged XCCY
+  options and matrices from the narrower Python and Excel staged result surfaces.
+- **FR7 - XCCY fixing contract:** The XCCY methodology shall document canonical
+  `FX[foreign/domestic]` names, reciprocal reverse-FX lookup, bidirectional reciprocity within
+  the implemented tolerance, positive finite snapshot observations, duplicate behavior, and
+  the unsettled-cashflow dependency closure for historical requests.
+- **FR8 - Jacobian and inverse semantics:** The yield-curve Jacobian and XCCY methodology
+  shall state joint matrix placement, dimensions, solved-state construction, exact/bumped/
+  approximate population rules, and the existing `tolerance_` scaling convention without
+  implying unavailable binding accessors.
+- **FR9 - Examples and performance navigation:** Current documentation shall list all three
+  registered C++ XCCY examples and the installed-surface Python joint example. It shall
+  describe `xccy_perf` as a 24-row execution-smoke surface, including its started-MTM basket
+  and reset-aware calibration coverage, without presenting it as a paired regression gate.
+- **FR10 - Component README accuracy:** Reconcile the core, public, Python, Excel, and web
+  READMEs with their actual current surfaces. The Python testing section shall include curve
+  and XCCY coverage. The Excel docs shall explicitly state which joint matrices are and are not
+  worksheet-visible.
+- **FR11 - Changelog separation:** `CHANGELOG.md` may update its current-capability baseline
+  and retain qualifying dated history. Current-state documents shall not contain delivery
+  chronology, superseded plans, or historical implementation narrative.
+- **FR12 - Verified no-change dispositions:** A document that needs no edit shall remain
+  untouched and be marked verified-current in the audit artifact with its inspected source
+  authorities. Passing `check_docs.py` alone is not sufficient evidence.
+
+## Non-Functional Requirements
+
+- **Accuracy:** Every changed technical claim must have direct evidence in current source,
+  tests, examples, generated registration, or build configuration.
+- **Compatibility:** Documentation-only changes must not alter public or internal behavior.
+- **Current-state style:** Methodology owns mathematical contracts and invariants; overview
+  pages summarize and link instead of duplicating detailed prose.
+- **Markdown:** Preserve GitHub-renderable math, valid relative links and anchors, aligned
+  tables, no trailing whitespace, and final newlines.
+- **Scope control:** The final tracked diff may contain published Markdown and Codex audit/
+  planning artifacts only. Generated and production files must remain unchanged.
+- **Reviewability:** Prefer small thematic commits so API corrections, architecture/
+  methodology reconciliation, and navigation updates can be reviewed independently.
+
+## Inputs and Outputs
+
+- **Published Markdown set:** `.github/scripts/check_docs.py::DOCS` is the
+  authority; the output is one 33-row disposition matrix.
+- **C++ surface:** core/public headers and generated enums are the authority;
+  the outputs are exact types, constants, ownership, and solver contracts.
+- **Python surface:** `dal-python/src/bindings/`, `dal-python/src/dal/`, tests,
+  and examples are the authorities; the outputs are callable names, result
+  properties, and supported workflows.
+- **Excel surface:** `dal-excel/src/`, interface markup, generated help, and
+  smoke tests are the authorities; the outputs are worksheet functions,
+  settings, selectors, and documented limitations.
+- **Build/runtime surface:** CMake, presets, scripts, workflows, and web source
+  are the authorities; the outputs are current setup, ownership, execution,
+  and CI descriptions.
+- **Numerical behavior:** methodology implementations and independent tests are
+  the authorities; the outputs are correct formulas, matrix semantics,
+  tolerances, and applicability.
+
+## Acceptance Criteria
+
+- [ ] The audit artifact contains exactly one evidence-backed disposition for each of the 33
+      Markdown files selected by `.github/scripts/check_docs.py`.
+- [ ] Every still-relevant finding from the prior codebase documentation audit is either
+      corrected in current docs or recorded as already resolved with current evidence.
+- [ ] The confirmed root/index, architecture, enum-spelling, XCCY fixing, joint inverse,
+      example, benchmark, Python testing, Excel availability, and changelog gaps are resolved.
+- [ ] Root and component overview pages remain concise and link to methodology/API documents
+      for detailed contracts.
+- [ ] `CLAUDE.md`, `.claude/`, generated files, third-party docs, production source, build
+      configuration, and workflows have no tracked changes.
+- [ ] `python3 .github/scripts/check_docs.py` passes.
+- [ ] `git diff --check` passes for the complete branch diff.
+- [ ] Documented runnable commands changed by the branch are executed or validated against the
+      already-built current targets, including XCCY examples and `xccy_perf` when referenced.
+- [ ] A fresh DAL reviewer reports no blocking documentation or source-consistency findings.
+- [ ] The final branch is pushed as a new documentation-only PR from merged `master`.
+
+## Open Questions
+
+None. The user selected the repository-wide audit and approved the documentation-only design.

CHANGELOG.md

@@ -27,31 +27,33 @@ here as the baseline rather than dated releases:
   calibrated to market instruments. See `docs/methodology/yield_curve.md`.
 - **Underdetermined Search** — constrained least-change solver for over-parameterised
   nonlinear calibration. See `docs/methodology/underdetermined_search.md`.
-- **Cross-Currency Calibration** — XCCY basis-curve fitting across two currencies. See
-  `docs/methodology/xccy_calibration.md`.
+- **Cross-Currency Pricing and Calibration** — fixed, resettable, and mark-to-market
+  swap pricing with immutable timestamped rate/FX fixing snapshots, staged basis
+  fitting, simultaneous domestic/foreign/basis calibration, and named joint
+  parameter/residual ranges. See `docs/methodology/xccy_calibration.md`.
 - **Interpolation** — linear, log-linear, cubic-spline, and mixed 1D interpolators plus
   bilinear 2D interpolation. See `docs/methodology/interpolation.md`.
 - **Log-Discount Curve** — node log-discount-factor parameterisation with `LogDfScheme_`
   interpolation schemes and scalar-generic passive/AAD evaluation. See
   `docs/methodology/log_discount_curve.md`.
-- **Yield-Curve Jacobian and Inverse-Jacobian Risk** — AAD forward Jacobian and the
-  inverse-Jacobian IR-risk transform, including the `effJacobianInverse_` unit convention.
-  See `docs/methodology/yield_curve_jacobian.md`.
+- **Yield-Curve Jacobian and Inverse-Jacobian Risk** — AAD forward Jacobians for every
+  implemented curve representation subject to the normal eligibility gates, plus the
+  inverse-Jacobian IR-risk transform and its `effJacobianInverse_` unit convention. See
+  `docs/methodology/yield_curve_jacobian.md`.
 - **Script Engine** — events-table to AST pipeline, visitor passes (domain analysis,
   constant-condition folding), and the fuzzy evaluator for pathwise AAD through
   discontinuous payoffs. See `docs/methodology/script_engine.md`.
-- **Analytic Jacobian for curve calibration (CurveJacobianMode flag)** — optional analytic
-  Jacobian mode for yield-curve calibration. See
-  `docs/methodology/yield_curve_jacobian.md`.
 
 ## 2026-07
 
 - `curve`: Added reset-aware cross-currency pricing and simultaneous domestic,
-  foreign, and basis calibration. `XccyNotionalMode_` now defines `FIXED`,
-  `RESETTABLE`, and `MARK_TO_MARKET`; explicit rate/FX fixing identities and one
-  immutable timestamped snapshot support already-started swaps; and the joint
-  solver exposes named parameter/residual ranges plus analytic or bumped
-  Jacobians through public C++, Python, and Excel. **Breaking:** the two
+  foreign, and basis calibration. Fixed, resettable, and mark-to-market notional
+  modes replace the prior boolean configuration; explicit rate/FX fixing identities
+  and one immutable timestamped snapshot support already-started swaps; and the
+  joint solver exposes named parameter/residual ranges plus analytic or bumped
+  Jacobians. Public C++ and joint Python expose both retained joint matrices. Excel
+  exposes the joint forward Jacobian and ranges, but has no worksheet getter for the
+  effective inverse. **Breaking:** the two
   `CrossCurrencyConvention_` booleans `resettableNotional_` and
   `markToMarketNotional_` are replaced by the enum in
   `CrossCurrencySwapConfig_`. The legacy fixed-notional convenience constructor

README.md

@@ -5,7 +5,7 @@
 [![Codacy Grade](https://app.codacy.com/project/badge/Grade/9c84afd2bb534c6c87584e5d6e4cc420)](https://app.codacy.com/app/wegamekinglc/Derivatives-Algorithms-Lib)
 [![Coverage Status](https://coveralls.io/repos/github/wegamekinglc/Derivatives-Algorithms-Lib/badge.svg?branch=master)](https://coveralls.io/github/wegamekinglc/Derivatives-Algorithms-Lib?branch=master)
 
-A C++17 quantitative finance library with built-in Automatic Adjoint Differentiation (AAD). Features include yield curve construction, Monte Carlo simulation, finite difference PDE solvers, a scripting engine for exotic payoffs with tree-walk and compiled evaluators, and parallel model evaluation.
+A C++17 quantitative finance library with built-in Automatic Adjoint Differentiation (AAD). Features include yield curve construction, cross-currency pricing and calibration, Monte Carlo simulation, finite difference PDE solvers, a scripting engine for exotic payoffs with tree-walk and compiled evaluators, and parallel model evaluation.
 
 ## Quick Start
 
@@ -93,6 +93,13 @@ d_vol   :    58.7140
 
 More examples: [Python](dal-python/examples/), [Excel](dal-excel/examples/), [C++](dal-cpp/examples/). The C++ Monte Carlo script examples show both tree-walk and compiled evaluator output where applicable.
 
+Cross-currency examples:
+
+- [reset-aware pricing](dal-cpp/examples/xccy_reset_pricing/)
+- [staged basis calibration](dal-cpp/examples/xccy_curve_calibration/)
+- [joint domestic/foreign/basis calibration](dal-cpp/examples/xccy_mtm_calibration/)
+- [Python joint calibration](dal-python/examples/007.xccy_joint_calibration.py)
+
 ### Script Engine Modes
 
 Monte Carlo script valuation defaults to the tree-walk evaluator (`compiled=false`).
@@ -152,6 +159,7 @@ Methodology notes (see the index above for the full list):
 
 - [AAD](docs/methodology/aad.md) — Automatic adjoint differentiation: expression templates, tape, propagation
 - [Yield Curve](docs/methodology/yield_curve.md) and [Yield-Curve Jacobian](docs/methodology/yield_curve_jacobian.md) — discount curves, calibration, Jacobian / inverse-Jacobian risk
+- [Cross-Currency Pricing and Calibration](docs/methodology/xccy_calibration.md) — fixed, resettable, and MTM swaps; immutable fixing snapshots; staged basis and simultaneous domestic/foreign/basis calibration
 - [Interpolation](docs/methodology/interpolation.md) — linear, log-linear, cubic interpolators
 - [PDE](docs/methodology/pde.md) — finite-difference meshers and coordinate maps
 - [Script Engine](docs/methodology/script_engine.md) — expression scripting, fuzzy AAD evaluation, and compiled evaluator parity

dal-excel/README.md

@@ -32,9 +32,11 @@ worksheet calls:
 
 Curve workflows use convention/instrument constructors followed by
 `CALIBRATE.SINGLECURVE`, `CALIBRATE.XCCYMARKET`, or
-`CALIBRATE.JOINTXCCY`; result accessors return diagnostics, matrices, ranges, or
-curve handles. The [public API guide](../docs/public-api.md#excel) lists the
-primary worksheet families.
+`CALIBRATE.JOINTXCCY`; result accessors return diagnostics, supported matrix or
+range views, and curve handles. Matrix visibility differs between staged and
+joint XCCY as described below. The
+[public API guide](../docs/public-api.md#excel) lists the primary worksheet
+families.
 
 ## Resettable and Joint XCCY Functions
 
@@ -47,8 +49,17 @@ domestic and foreign rate-fixing identities. Pass that handle to
 `MARKETFIXINGSNAPSHOT.NEW` takes parallel index-name, fixing-time, and value
 ranges and returns one immutable snapshot handle. The arrays must have equal
 length, timestamps must be valid, and observations must be positive and finite.
-The snapshot can contain both rate and canonical FX names such as
-`FX[EUR/USD]`.
+Repeated `(index name, timestamp)` rows are rejected. The canonical name for a
+domestic/foreign pair is `FX[foreign/domestic]`, for example `FX[EUR/USD]` for
+USD/EUR. Lookup uses the requested direction when present and otherwise uses
+the reciprocal of the reverse canonical observation. If both directions are
+present at one timestamp, their product must differ from one by no more than
+`1e-10`.
+
+Staged `CALIBRATE.XCCYMARKET` returns a basis-curve handle plus fit diagnostics.
+`XCCYCALIBRATIONRESULT.GET` exposes `marketRates`, `modelRates`, `residuals`,
+`maxAbsResidual`, and `rmsResidual`; neither the staged forward Jacobian nor the
+staged effective inverse is worksheet-visible.
 
 `CALIBRATE.JOINTXCCY` performs one domestic/foreign/basis solve. Its result
 supports dedicated handle getters:
@@ -57,10 +68,13 @@ supports dedicated handle getters:
 - `JOINTXCCYCALIBRATIONRESULT.GET.FOREIGNBLOCK`
 - `JOINTXCCYCALIBRATIONRESULT.GET.BASISCURVE`
 
-`JOINTXCCYCALIBRATIONRESULT.GET` returns matrix views selected by
+Joint settings can request both forward-Jacobian and effective-inverse
+computation. `JOINTXCCYCALIBRATIONRESULT.GET` returns views selected by
 `fxForwards`, `marketRates`, `modelRates`, `residuals`, `jacobian`,
-`parameterRanges`, or `residualRanges`. The generated HTML under `auto/` is the
-exact argument and settings-key reference.
+`parameterRanges`, or `residualRanges`; `jacobian` is the worksheet-visible
+forward matrix and the range selectors publish its named layout. No worksheet
+selector exposes the retained joint effective inverse. The generated HTML
+under `auto/` is the exact argument and settings-key reference.
 
 ## Layout and Generated Registration