quantvolt 0.1.0__tar.gz → 0.2.0__tar.gz

{quantvolt-0.1.0 → quantvolt-0.2.0}/Cargo.lock

@@ -237,7 +237,7 @@ dependencies = [
 
 [[package]]
 name = "quantvolt-core"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "ndarray 0.17.2",
  "numpy",

{quantvolt-0.1.0 → quantvolt-0.2.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "quantvolt-core"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2021"
 publish = false
 readme = "README.md"
@@ -27,4 +27,3 @@ rand_distr = "0.6"
 # reduction in CI wheel-build time.
 [profile.release]
 lto = "thin"
-

{quantvolt-0.1.0 → quantvolt-0.2.0}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: quantvolt
-Version: 0.1.0
+Version: 0.2.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Rust
 Classifier: Topic :: Office/Business :: Financial :: Investment
 Classifier: Topic :: Scientific/Engineering :: Mathematics
@@ -28,7 +30,7 @@ Summary: Quantitative analysis of European power and energy markets
 Keywords: energy,power,gas,carbon,quant,derivatives,risk-management,pricing,monte-carlo,forward-curve
 Author-email: Nima Bahrami <nima@skillmix.nl>
 License-Expression: MIT
-Requires-Python: >=3.12
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: Documentation, https://nimabahrami.github.io/quantvolt/
 Project-URL: Homepage, https://nimabahrami.github.io/quantvolt/
@@ -51,9 +53,24 @@ Covered markets: EEX Phelix DE/AT power, EPEX SPOT power (DE, FR, NL, BE, GB), T
 natural gas (ICE Endex), and EUA carbon allowances — extensible by the caller without editing
 library source. See [docs/european-markets.md](docs/european-markets.md).
 
+## Why QuantVolt?
+
+A typical desk assembles a curve spreadsheet, a standalone options pricer, a storage/dispatch
+optimizer and a bolted-on VaR tool, each with its own units, sign conventions and delivery-period
+identity — hand-reconciling between them is slow and a recurring source of quiet errors. QuantVolt
+instead moves the same immutable `ForwardCurve` / `DeliveryPeriod` / `MarketData` / `Greeks` value
+objects through curve construction, pricing, portfolio valuation, risk, realized settlement and
+physical-asset valuation, with determinism, eager validation and serializability enforced
+structurally rather than left to convention. It is equally explicit about scope: a PPA stays
+`unpriced` until you register a forward-looking pricer, storage/dispatch results are brought into
+a portfolio explicitly, no market data ships with the package, and approximations (Kirk,
+Turnbull-Wakeman, `bang_bang`) are labelled, never hidden. See
+[the "Why QuantVolt?" page](https://nimabahrami.github.io/quantvolt/#/guide/why) and the
+[external validation evidence](docs/validation.md) for the checkable version of these claims.
+
 ## Install
 
-Requires Python 3.12+.
+Requires Python 3.11+.
 
 ```bash
 uv add quantvolt            # or: pip install quantvolt
@@ -295,7 +312,7 @@ specialised names stay on their sub-package. Full reference with a runnable exam
 | `quantvolt.stats` | Descriptive statistics, normality tests, ADF/KPSS stationarity with Samuelson-effect detection, correlation, Ornstein-Uhlenbeck mean reversion |
 | `quantvolt.market` | Transmission cost, temperature/degree-day utilities, generation outage / reliability KPIs |
 | `quantvolt.workflow` | 7-step model-selection workflow for structured products |
-| `quantvolt.portfolio` | `Portfolio`/`Position` book assembly, forward-looking `value_portfolio`, and realized interval `settle_energy_portfolio` aggregation |
+| `quantvolt.portfolio` | `Portfolio`/`Position` book assembly; `value_portfolio` natively prices futures, forwards, swaps, transmission/pipeline rights, vanilla options, spread options and tolling agreements via the caller-extensible `DEFAULT_PRICERS` registry (PPAs and realized hedges are valued via a caller-registered pricer, e.g. `make_ppa_pricer` — deliberately not a default); realized interval `settle_energy_portfolio` aggregation is kept structurally separate from that forward-looking NPV |
 | `quantvolt.data` | Optional (`quantvolt[data]`): provider adapters behind a `DataSource` protocol — the only package that performs I/O |
 | `quantvolt.testing` | `assert_input_unchanged` — shipped test utility for the no-mutation invariant |
 | `quantvolt.exceptions` | The `EnergyQuantError` hierarchy (`ValidationError`, `ArbitrageError`, `MissingTenorError`, …) |
@@ -317,11 +334,20 @@ positions. See [docs/risk-and-assets.md](docs/risk-and-assets.md).
 
 ## Documentation
 
+- [Why QuantVolt?](https://nimabahrami.github.io/quantvolt/#/guide/why) — the integration problem,
+  the shared computational model, the extensible pricer registry, and an honest "what QuantVolt is
+  not" section
 - [docs/api.md](docs/api.md) — module-by-module API reference with runnable examples
 - [docs/risk-and-assets.md](docs/risk-and-assets.md) — the VaR family, the physical-vs-risk-neutral
   drift rule, incomplete-market hedging, dispatch & storage, and the long-dated / liquidity caveats
 - [docs/european-markets.md](docs/european-markets.md) — market coverage, power-vs-gas
   statistics, negative prices, Samuelson effect, carbon costs, data-source policy
+- [docs/validation.md](docs/validation.md) — external validation evidence: QuantVolt's pricers
+  checked against QuantLib 1.43 golden fixtures, with honest caveats and regeneration instructions
+- Three complete, runnable end-to-end tutorials (site, each backed by a `site/examples/
+  verify_tutorial_*.py` script): [spark spread to hedge](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-spark),
+  [renewable PPA to CFaR](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-ppa), and
+  [storage intrinsic to hedge](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-storage)
 - `.kiro/steering/` — product, tech, structure, and coding-style standards
 - `.kiro/specs/power-energy-quant-analysis/` — requirements, design, and task breakdown
   (the library is spec-driven; the design document is the source of truth for the maths)

{quantvolt-0.1.0 → quantvolt-0.2.0}/README.md

@@ -14,9 +14,24 @@ Covered markets: EEX Phelix DE/AT power, EPEX SPOT power (DE, FR, NL, BE, GB), T
 natural gas (ICE Endex), and EUA carbon allowances — extensible by the caller without editing
 library source. See [docs/european-markets.md](docs/european-markets.md).
 
+## Why QuantVolt?
+
+A typical desk assembles a curve spreadsheet, a standalone options pricer, a storage/dispatch
+optimizer and a bolted-on VaR tool, each with its own units, sign conventions and delivery-period
+identity — hand-reconciling between them is slow and a recurring source of quiet errors. QuantVolt
+instead moves the same immutable `ForwardCurve` / `DeliveryPeriod` / `MarketData` / `Greeks` value
+objects through curve construction, pricing, portfolio valuation, risk, realized settlement and
+physical-asset valuation, with determinism, eager validation and serializability enforced
+structurally rather than left to convention. It is equally explicit about scope: a PPA stays
+`unpriced` until you register a forward-looking pricer, storage/dispatch results are brought into
+a portfolio explicitly, no market data ships with the package, and approximations (Kirk,
+Turnbull-Wakeman, `bang_bang`) are labelled, never hidden. See
+[the "Why QuantVolt?" page](https://nimabahrami.github.io/quantvolt/#/guide/why) and the
+[external validation evidence](docs/validation.md) for the checkable version of these claims.
+
 ## Install
 
-Requires Python 3.12+.
+Requires Python 3.11+.
 
 ```bash
 uv add quantvolt            # or: pip install quantvolt
@@ -258,7 +273,7 @@ specialised names stay on their sub-package. Full reference with a runnable exam
 | `quantvolt.stats` | Descriptive statistics, normality tests, ADF/KPSS stationarity with Samuelson-effect detection, correlation, Ornstein-Uhlenbeck mean reversion |
 | `quantvolt.market` | Transmission cost, temperature/degree-day utilities, generation outage / reliability KPIs |
 | `quantvolt.workflow` | 7-step model-selection workflow for structured products |
-| `quantvolt.portfolio` | `Portfolio`/`Position` book assembly, forward-looking `value_portfolio`, and realized interval `settle_energy_portfolio` aggregation |
+| `quantvolt.portfolio` | `Portfolio`/`Position` book assembly; `value_portfolio` natively prices futures, forwards, swaps, transmission/pipeline rights, vanilla options, spread options and tolling agreements via the caller-extensible `DEFAULT_PRICERS` registry (PPAs and realized hedges are valued via a caller-registered pricer, e.g. `make_ppa_pricer` — deliberately not a default); realized interval `settle_energy_portfolio` aggregation is kept structurally separate from that forward-looking NPV |
 | `quantvolt.data` | Optional (`quantvolt[data]`): provider adapters behind a `DataSource` protocol — the only package that performs I/O |
 | `quantvolt.testing` | `assert_input_unchanged` — shipped test utility for the no-mutation invariant |
 | `quantvolt.exceptions` | The `EnergyQuantError` hierarchy (`ValidationError`, `ArbitrageError`, `MissingTenorError`, …) |
@@ -280,11 +295,20 @@ positions. See [docs/risk-and-assets.md](docs/risk-and-assets.md).
 
 ## Documentation
 
+- [Why QuantVolt?](https://nimabahrami.github.io/quantvolt/#/guide/why) — the integration problem,
+  the shared computational model, the extensible pricer registry, and an honest "what QuantVolt is
+  not" section
 - [docs/api.md](docs/api.md) — module-by-module API reference with runnable examples
 - [docs/risk-and-assets.md](docs/risk-and-assets.md) — the VaR family, the physical-vs-risk-neutral
   drift rule, incomplete-market hedging, dispatch & storage, and the long-dated / liquidity caveats
 - [docs/european-markets.md](docs/european-markets.md) — market coverage, power-vs-gas
   statistics, negative prices, Samuelson effect, carbon costs, data-source policy
+- [docs/validation.md](docs/validation.md) — external validation evidence: QuantVolt's pricers
+  checked against QuantLib 1.43 golden fixtures, with honest caveats and regeneration instructions
+- Three complete, runnable end-to-end tutorials (site, each backed by a `site/examples/
+  verify_tutorial_*.py` script): [spark spread to hedge](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-spark),
+  [renewable PPA to CFaR](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-ppa), and
+  [storage intrinsic to hedge](https://nimabahrami.github.io/quantvolt/#/guide/tutorial-storage)
 - `.kiro/steering/` — product, tech, structure, and coding-style standards
 - `.kiro/specs/power-energy-quant-analysis/` — requirements, design, and task breakdown
   (the library is spec-driven; the design document is the source of truth for the maths)

{quantvolt-0.1.0 → quantvolt-0.2.0}/pyproject.toml

@@ -4,10 +4,10 @@ build-backend = "maturin"
 
 [project]
 name = "quantvolt"
-version = "0.1.0"
+version = "0.2.0"
 description = "Quantitative analysis of European power and energy markets"
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.11"
 license = "MIT"
 license-files = ["LICENSE"]
 authors = [{ name = "Nima Bahrami", email = "nima@skillmix.nl" }]
@@ -28,7 +28,9 @@ classifiers = [
     "Intended Audience :: Financial and Insurance Industry",
     "Intended Audience :: Science/Research",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Programming Language :: Rust",
     "Topic :: Office/Business :: Financial :: Investment",
     "Topic :: Scientific/Engineering :: Mathematics",
@@ -61,12 +63,20 @@ dev = [
     "maturin>=1.7,<2.0",
 ]
 
+# PEP 735 dependency group for OFFLINE external-validation fixture generation only.
+# NOT a [project.optional-dependencies] extra and NOT a core/runtime dependency: the
+# analytics core never imports QuantLib, CI never installs this group, and the generator
+# scripts under scripts/ (wheel-excluded above) are the only consumers. See
+# .kiro/specs/external-validation/ and docs/validation.md for the regeneration workflow.
+[dependency-groups]
+validation = ["QuantLib>=1.34"]
+
 [tool.maturin]
 python-source = "src"
 module-name = "quantvolt._core"
-# abi3-py312: build a single stable-ABI wheel that works on CPython 3.12+
+# abi3-py311: build a single stable-ABI wheel that works on CPython 3.11+
 # (one compile per platform instead of one per Python version).
-features = ["pyo3/extension-module", "pyo3/abi3-py312"]
+features = ["pyo3/extension-module", "pyo3/abi3-py311"]
 # Keep the sdist to the buildable package only. The docs site, rendered docs,
 # research data, helper scripts, and the logo are not part of the installable
 # library and would only bloat the distribution.
@@ -90,12 +100,20 @@ exclude = [
 [tool.ruff]
 line-length = 100
 src = ["src", "tests"]
+target-version = "py311"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
 
+[tool.ruff.lint.per-file-ignores]
+# Authored documentation text (AUTHORED_DOCS) carries long human-readable lines;
+# RUF001 flags the en-dashes used deliberately in that prose.
+"site/build_api.py" = ["E501", "RUF001"]
+# One-off internal refactoring tool, not shipped code.
+"site/tools/refactor_reference_design.py" = ["E501"]
+
 [tool.mypy]
-python_version = "3.12"
+python_version = "3.11"
 strict = true
 files = ["src/quantvolt"]
 

{quantvolt-0.1.0 → quantvolt-0.2.0}/rust/src/paths.rs

@@ -490,11 +490,11 @@ pub fn simulate_correlated_forwards_term_core(
         if antithetic {
             write_record(&mut data, p_minus, 0, rec, dim, &minus);
         }
-        for step in 0..steps {
+        for (step, factor) in factors.iter().enumerate().take(steps) {
             for e in &mut eps {
                 *e = rng.sample::<f64, _>(StandardNormal);
             }
-            matvec_lower(&factors[step], &eps, dim, &mut incr);
+            matvec_lower(factor, &eps, dim, &mut incr);
             let offset = step * dim;
             for d in 0..dim {
                 if active_steps[offset + d] {

{quantvolt-0.1.0 → quantvolt-0.2.0}/src/quantvolt/__init__.py

@@ -22,6 +22,7 @@ from .assets import (
     PhysicalFactorMapping,
     PlantModel,
     StorageModel,
+    ValuationSource,
     bang_bang,
     dispatch_deterministic,
     dispatch_value,
@@ -70,7 +71,12 @@ from .hedging import (
 )
 from .models import (
     BUILT_IN_COMMODITIES,
+    CachedAssetValuation,
+    CapFloorStripContract,
+    CapFloorType,
+    ChangeInLawAllocation,
     CommodityConfig,
+    CurtailmentTreatment,
     CurveNode,
     DeliveryPeriod,
     DeliverySchedule,
@@ -81,24 +87,43 @@ from .models import (
     Granularity,
     Greeks,
     Hub,
+    IndexationStep,
     InstrumentPriceRecord,
     Moneyness,
+    NegativePriceClause,
+    NegativePriceTreatment,
+    OptionSide,
+    OptionType,
     PipelineRight,
     PlantConfig,
     PowerDeliveryInterval,
     PowerHedgeContract,
     PowerHedgePosition,
     PowerHedgeType,
+    PpaAvailabilityGuarantee,
     PpaContract,
+    PpaContractMetadata,
+    PpaCreditSupportType,
+    PpaPriceTerms,
+    PpaReconciliationPeriod,
+    PpaReconciliationTerms,
     PpaSettlementType,
+    PpaTerms,
+    PpaToleranceBand,
     PpaVolumeBasis,
+    PpaVolumeTerms,
+    PriceUnit,
     RiskType,
     SettlementType,
+    SpreadOptionContract,
     SwapContract,
+    TollingAgreement,
     TransmissionRight,
     TransportDirection,
+    VanillaOptionContract,
     VolatilitySurface,
     VolatilityTenor,
+    convert_price,
 )
 from .portfolio import (
     Instrument,
@@ -114,6 +139,8 @@ from .portfolio import (
 )
 from .pricing import (
     AsianOptionRequest,
+    BachelierOptionRequest,
+    BachelierOptionResult,
     BarrierOptionRequest,
     CapFloorRequest,
     CapFloorResult,
@@ -129,6 +156,11 @@ from .pricing import (
     PowerHedgeSettlement,
     PpaDataColumns,
     PpaIntervalSettlement,
+    PpaPeriodValuation,
+    PpaPeriodVolume,
+    PpaReconciliationColumns,
+    PpaValuationResult,
+    PpaVolumeProfile,
     SpreadOptionRequest,
     SpreadOptionResult,
     SwapPricingResult,
@@ -147,19 +179,23 @@ from .pricing import (
     futures_delta,
     implied_heat_rate,
     implied_vol,
+    make_ppa_pricer,
     mark_to_market,
     power_cap_payoff,
     power_floor_payoff,
     price_asian,
+    price_bachelier_option,
     price_barrier,
     price_cap_floor,
     price_futures,
     price_lookback,
+    price_ppa,
     price_spark_spread_option,
     price_spread_option,
     price_swap,
     price_tolling_agreement,
     price_vanilla_option,
+    reconcile_ppa_ledger,
     settle_power_hedge_interval,
     settle_power_hedges_frame,
     settle_ppa_frame,
@@ -188,7 +224,7 @@ from .risk import (
     parametric_var,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 
 __all__ = [
     "BUILT_IN_COMMODITIES",
@@ -197,13 +233,20 @@ __all__ = [
     "ArbitrageWarning",
     "AsianOptionRequest",
     "AuthenticationError",
+    "BachelierOptionRequest",
+    "BachelierOptionResult",
     "BangBangHedgeWarning",
     "BarrierOptionRequest",
+    "CachedAssetValuation",
     "CapFloorRequest",
     "CapFloorResult",
+    "CapFloorStripContract",
+    "CapFloorType",
     "CashflowStrategyComparison",
     "CashflowStrategyMetrics",
+    "ChangeInLawAllocation",
     "CommodityConfig",
+    "CurtailmentTreatment",
     "CurveBuildResult",
     "CurveBuilder",
     "CurveNode",
@@ -229,6 +272,7 @@ __all__ = [
     "Greeks",
     "Hub",
     "ImpliedVolResult",
+    "IndexationStep",
     "Instrument",
     "InstrumentPriceRecord",
     "InsufficientDataError",
@@ -243,8 +287,12 @@ __all__ = [
     "MtMResult",
     "MultifactorForwardModel",
     "NativeExtensionError",
+    "NegativePriceClause",
+    "NegativePriceTreatment",
     "NoPricingDataError",
     "NumericalError",
+    "OptionSide",
+    "OptionType",
     "PhysicalFactorMapping",
     "PipelineRight",
     "PlantConfig",
@@ -259,16 +307,31 @@ __all__ = [
     "PowerHedgePosition",
     "PowerHedgeSettlement",
     "PowerHedgeType",
+    "PpaAvailabilityGuarantee",
     "PpaContract",
+    "PpaContractMetadata",
+    "PpaCreditSupportType",
     "PpaDataColumns",
     "PpaIntervalSettlement",
     "PpaNominationCandidate",
     "PpaNominationColumns",
     "PpaNominationFit",
     "PpaNominationObjective",
+    "PpaPeriodValuation",
+    "PpaPeriodVolume",
+    "PpaPriceTerms",
+    "PpaReconciliationColumns",
+    "PpaReconciliationPeriod",
+    "PpaReconciliationTerms",
     "PpaSettlementType",
+    "PpaTerms",
+    "PpaToleranceBand",
+    "PpaValuationResult",
     "PpaVolumeBasis",
+    "PpaVolumeProfile",
+    "PpaVolumeTerms",
     "PpaWalkForwardResult",
+    "PriceUnit",
     "PricedPosition",
     "RateLimitError",
     "RiskEngine",
@@ -281,16 +344,20 @@ __all__ = [
     "SchwartzSmithParams",
     "SettledPortfolioPosition",
     "SettlementType",
+    "SpreadOptionContract",
     "SpreadOptionRequest",
     "SpreadOptionResult",
     "StorageModel",
     "SwapContract",
     "SwapPricingResult",
+    "TollingAgreement",
     "TollingResult",
     "TransmissionRight",
     "TransportDirection",
     "TransportRightResult",
     "ValidationError",
+    "ValuationSource",
+    "VanillaOptionContract",
     "VanillaOptionRequest",
     "VanillaOptionResult",
     "VolatilitySurface",
@@ -307,6 +374,7 @@ __all__ = [
     "classify_moneyness",
     "clean_spread",
     "compare_cashflow_strategies",
+    "convert_price",
     "crack_spread",
     "credit_var",
     "dark_spread",
@@ -321,21 +389,25 @@ __all__ = [
     "implied_heat_rate",
     "implied_vol",
     "linear_cross_hedge",
+    "make_ppa_pricer",
     "mark_to_market",
     "monte_carlo_var",
     "parametric_var",
     "power_cap_payoff",
     "power_floor_payoff",
     "price_asian",
+    "price_bachelier_option",
     "price_barrier",
     "price_cap_floor",
     "price_futures",
     "price_lookback",
+    "price_ppa",
     "price_spark_spread_option",
     "price_spread_option",
     "price_swap",
     "price_tolling_agreement",
     "price_vanilla_option",
+    "reconcile_ppa_ledger",
     "settle_energy_portfolio",
     "settle_power_hedge_interval",
     "settle_power_hedges_frame",

{quantvolt-0.1.0 → quantvolt-0.2.0}/src/quantvolt/assets/dispatch_sdp.py

@@ -771,7 +771,13 @@ def _dispatch_lsm(
                 conditions.append(float(np.linalg.cond(basis)))
                 predicted = basis @ coeffs
                 continuation = {s: predicted[:, j] for j, s in enumerate(feasible_next)}
-                coefficients = {s: coeffs[:, j].copy() for j, s in enumerate(feasible_next)}
+                # .astype(np.float64) (not .copy()): numpy's lstsq stub types its first
+                # return value as floating[Any] on some numpy releases (narrower Vector =
+                # NDArray[float64] elsewhere) -- this pins the static (and, since the data
+                # is already float64, identical-at-runtime) dtype across numpy versions.
+                coefficients = {
+                    s: coeffs[:, j].astype(np.float64) for j, s in enumerate(feasible_next)
+                }
             else:
                 # A min-run-locked online state whose derated capacity has collapsed
                 # below every feasible level on *some* paths realizes -inf there (a
@@ -799,7 +805,7 @@ def _dispatch_lsm(
                     step_conditions.append(float(np.linalg.cond(design)))
                     predicted_s = basis @ coeffs_s
                     continuation[state] = np.where(finite, predicted_s, -np.inf)
-                    coefficients[state] = coeffs_s.copy()
+                    coefficients[state] = coeffs_s.astype(np.float64)
                 conditions.append(max(step_conditions, default=1.0))
         policy_coefficients.append(coefficients)
 

{quantvolt-0.1.0 → quantvolt-0.2.0}/src/quantvolt/assets/long_dated.py

@@ -18,11 +18,15 @@ long-dated risk is never understated (Req 23):
 
 Tagging semantics
 -----------------
-:class:`ValuationSource` is the single vocabulary of provenance tags. Its two
-values, ``"forward"`` and ``"projected"``, are exactly the strings a caller should
-propagate onto a :class:`~quantvolt.portfolio.model.Position`'s ``tags`` so that
-downstream risk code can tell the regimes apart. :class:`BenchmarkResult` carries
-the tag prominently in its ``source`` field.
+:class:`ValuationSource` (``models/instruments.py``) is the single vocabulary of
+provenance tags. This module produces two of its values, ``"forward"`` and
+``"projected"`` -- exactly the strings a caller should propagate onto a
+:class:`~quantvolt.portfolio.model.Position`'s ``tags`` so that downstream risk code
+can tell the regimes apart. :class:`BenchmarkResult` carries the tag prominently in
+its ``source`` field. A third value, ``"simulated"``, is produced elsewhere (the
+portfolio-native-pricers spec's ``CachedAssetValuation`` wrapper, Req 19) for a
+precomputed LSMC/dispatch cache -- a third regime this module does not itself
+produce, tagged the same way for the same reason (Property-66 pattern).
 
 Intended wiring (this module does not touch ``risk/``)
 ------------------------------------------------------
@@ -62,10 +66,10 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from dataclasses import dataclass
-from enum import StrEnum
 
 from ..exceptions import MissingTenorError, ValidationError
 from ..models.curve import ForwardCurve
+from ..models.instruments import ValuationSource as ValuationSource  # explicit re-export
 from ..models.schedule import DeliveryPeriod
 from ..numerics.risk_adjustment import PriceOfRiskKind
 from ..portfolio.model import PricedPosition
@@ -73,17 +77,12 @@ from ..portfolio.model import PricedPosition
 # A pure projection of a period to its model spot expectation (documented, never mutated).
 SpotModel = Callable[[DeliveryPeriod], float]
 
-
-class ValuationSource(StrEnum):
-    """Provenance of a long-dated valuation; the tag that separates the two regimes.
-
-    The string values double as the ``Position.tags`` markers a caller propagates so
-    that :func:`var_applicability_guard` (and any risk code) can tell a projected
-    value apart from a forward-based one.
-    """
-
-    FORWARD = "forward"  # liquid forward curve covers the period (Req 23.1)
-    PROJECTED = "projected"  # projected from a spot model + corporate premium (Req 23.2)
+# ``ValuationSource`` is now defined in ``models/instruments.py`` (the portfolio-native-pricers
+# spec, Req 19, reuses it for a THIRD regime -- a precomputed LSMC/dispatch cache -- and
+# ``models/instruments.py`` is the leaf-ish module every instrument-bearing type can import
+# without a cycle back through ``portfolio/model.py``, which this module already depends on).
+# Imported here (not re-defined) so there remains exactly one provenance vocabulary; every
+# existing ``from quantvolt.assets.long_dated import ValuationSource`` import keeps working.
 
 
 @dataclass(frozen=True, slots=True)

{quantvolt-0.1.0 → quantvolt-0.2.0}/src/quantvolt/cli.py

@@ -6,11 +6,52 @@ import argparse
 import json
 from dataclasses import asdict
 from importlib import import_module
+from pathlib import Path
+from typing import Any, Protocol, cast
 
 
-def _datasets():
+class _DatasetRecordLike(Protocol):
+    """Structural stand-in for ``quantvolt.data.datasets.DatasetRecord``.
+
+    The core (including this CLI entry point) must never statically import
+    ``quantvolt.data`` (Req 12.1; enforced by
+    ``tests/unit/test_data_isolation.py::test_no_core_source_file_imports_the_data_layer``),
+    so this protocol names only the attributes the CLI itself reads rather than importing
+    the real dataclass.
+    """
+
+    dataset_id: str
+    version: str
+    filename: str
+    size: int
+    sha256: str
+    format: str
+    license: str
+    source: str
+    url: str
+
+
+class _DatasetsModule(Protocol):
+    """Structural type for the ``quantvolt.data.datasets`` submodule.
+
+    ``quantvolt.data.datasets`` is imported lazily by name (rather than with a normal
+    ``import`` statement) so that CLI subcommands other than ``data`` never trigger the
+    optional ``quantvolt[data]`` extra's dependency (``httpx``, pulled in transitively via
+    ``quantvolt.data.__init__``). This protocol lets mypy still check the call sites below
+    against the submodule's real signatures without a static import of the data layer.
+    """
+
+    def list_datasets(self) -> tuple[_DatasetRecordLike, ...]: ...
+    def info(self, dataset_id: str) -> _DatasetRecordLike: ...
+    def fetch(self, dataset_id: str, *, force: bool = ..., offline: bool = ...) -> Path: ...
+    def verify(self, dataset_id: str) -> bool: ...
+    def path(self, dataset_id: str) -> Path: ...
+    def remove(self, dataset_id: str) -> bool: ...
+
+
+def _datasets() -> _DatasetsModule:
     """Load the optional data layer only after the CLI is invoked."""
-    return import_module("quantvolt.data.datasets")
+    return cast("_DatasetsModule", import_module("quantvolt.data.datasets"))
 
 
 def _parser() -> argparse.ArgumentParser:
@@ -36,14 +77,14 @@ def main(argv: list[str] | None = None) -> int:
     if args.operation == "list":
         records = datasets.list_datasets()
         if args.as_json:
-            print(json.dumps([asdict(record) for record in records], indent=2))
+            print(json.dumps([asdict(cast(Any, record)) for record in records], indent=2))
         else:
             for record in records:
                 print(f"{record.dataset_id:38} {record.version:8} {record.size:>10} bytes")
         return 0
     dataset_id = args.dataset_id
     if args.operation == "info":
-        print(json.dumps(asdict(datasets.info(dataset_id)), indent=2))
+        print(json.dumps(asdict(cast(Any, datasets.info(dataset_id))), indent=2))
     elif args.operation == "fetch":
         print(datasets.fetch(dataset_id, force=args.force, offline=args.offline))
     elif args.operation == "verify":

{quantvolt-0.1.0 → quantvolt-0.2.0}/src/quantvolt/data/datasets.py

@@ -38,7 +38,8 @@ class DatasetRecord:
 
 def _catalog() -> dict[str, Any]:
     resource = files("quantvolt.data").joinpath(_CATALOG_RESOURCE)
-    return json.loads(resource.read_text(encoding="utf-8"))
+    catalog: dict[str, Any] = json.loads(resource.read_text(encoding="utf-8"))
+    return catalog
 
 
 def _record(dataset_id: str) -> DatasetRecord: