portlearn 0.0.1.dev1__tar.gz → 0.0.1.dev2__tar.gz

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev2}/CHANGELOG.md

@@ -8,6 +8,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.0.1.dev2]
+
+### Added
+
+- Portfolio weights: the `portlearn.weights` module with the closed portfolio-role vocabulary, target-weight validation, and immutable weight books.
+- Rebalancing: schedule policies and the drift law carrying held weights across holding segments (`portlearn.rebalance`).
+- Transaction and turnover accounting with proportional transaction-cost models (`portlearn.trades`, `portlearn.turnover`, `portlearn.costs`).
+- The transaction ledger: segment-composed accounting over the wealth path with the reference accounting engine (`portlearn.ledger`).
+- The strategy decision-contract seam — `Strategy.decide(context) -> DecisionResult` over `DecisionContext`, validated by `require_decision_result_compatible`.
+- Lazy module facades for the portfolio modules under the top-level package namespace.
+- Public test modules covering the portfolio-weight, rebalance, transaction, cost, ledger, and decision-contract surfaces.
+
+### Changed
+
+### Fixed
+
+### Deprecated
+
+### Removed
+
 ## [0.0.1.dev1]
 
 ### Added

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: portlearn
-Version: 0.0.1.dev1
+Version: 0.0.1.dev2
 Summary: Finance-first research framework for controlled, reproducible, and modular experimentation in machine-learned portfolio choice.
 Project-URL: Repository, https://github.com/fmasoudy/PortLearn
 Project-URL: Issues, https://github.com/fmasoudy/PortLearn/issues
@@ -16,8 +16,8 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/png/monochrome/portlearn-logo-horizontal-white.png">
-    <img src="docs/assets/brand/png/primary/portlearn-logo-horizontal.png" alt="PortLearn logo: a rounded navy-and-teal PL monogram with a segmented circular motif, beside the PortLearn wordmark" width="460">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fmasoudy/PortLearn/main/docs/assets/brand/png/monochrome/portlearn-logo-horizontal-white.png">
+    <img src="https://raw.githubusercontent.com/fmasoudy/PortLearn/main/docs/assets/brand/png/primary/portlearn-logo-horizontal.png" alt="PortLearn logo: a rounded navy-and-teal PL monogram with a segmented circular motif, beside the PortLearn wordmark" width="460">
   </picture>
 </p>
 
@@ -63,6 +63,11 @@ PortLearn is under active research development. This roadmap is intentionally hi
 - Chronologically valid feature transforms: lags, rolling statistics, scalers, and carry-forward.
 - Contracts for the forecasting and estimation lifecycle (fitting, refitting, forecast timing, tuning, seeds, determinism, provenance); estimators are not provided yet.
 - Descriptive research-dataset diagnostics (summary, correlation, coverage, missingness) with renderer-neutral plotting; rendering is available through the optional `plot` extra.
+- Portfolio weights: target-weight validation, weight books, and the closed portfolio-role vocabulary, under the `portlearn.weights` module.
+- Rebalancing: schedule policies and the drift law that carries held weights across holding segments (`portlearn.rebalance`).
+- Transaction ledger: segment-composed accounting over the wealth path, built on immutable per-period ledger records with retained execution details, and the reference accounting engine (`portlearn.ledger`).
+- Trading and cost accounting: cost-aware transaction and turnover accounting with proportional cost models (`portlearn.trades`, `portlearn.turnover`, `portlearn.costs`).
+- The strategy decision-contract seam: `Strategy.decide(context) -> DecisionResult` over `DecisionContext` — the decision-time aggregate of forecast, information, holdings, and strategy state — validated by `require_decision_result_compatible`.
 
 **Next**
 
@@ -71,7 +76,6 @@ PortLearn is under active research development. This roadmap is intentionally hi
 
 **Planned**
 
-- Portfolio construction and accounting.
 - Later deep-learning and reinforcement-learning research capabilities.
 
 Entries move forward on this roadmap as the underlying research foundation stabilizes; nothing here is a dated commitment.

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev2}/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/png/monochrome/portlearn-logo-horizontal-white.png">
-    <img src="docs/assets/brand/png/primary/portlearn-logo-horizontal.png" alt="PortLearn logo: a rounded navy-and-teal PL monogram with a segmented circular motif, beside the PortLearn wordmark" width="460">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fmasoudy/PortLearn/main/docs/assets/brand/png/monochrome/portlearn-logo-horizontal-white.png">
+    <img src="https://raw.githubusercontent.com/fmasoudy/PortLearn/main/docs/assets/brand/png/primary/portlearn-logo-horizontal.png" alt="PortLearn logo: a rounded navy-and-teal PL monogram with a segmented circular motif, beside the PortLearn wordmark" width="460">
   </picture>
 </p>
 
@@ -47,6 +47,11 @@ PortLearn is under active research development. This roadmap is intentionally hi
 - Chronologically valid feature transforms: lags, rolling statistics, scalers, and carry-forward.
 - Contracts for the forecasting and estimation lifecycle (fitting, refitting, forecast timing, tuning, seeds, determinism, provenance); estimators are not provided yet.
 - Descriptive research-dataset diagnostics (summary, correlation, coverage, missingness) with renderer-neutral plotting; rendering is available through the optional `plot` extra.
+- Portfolio weights: target-weight validation, weight books, and the closed portfolio-role vocabulary, under the `portlearn.weights` module.
+- Rebalancing: schedule policies and the drift law that carries held weights across holding segments (`portlearn.rebalance`).
+- Transaction ledger: segment-composed accounting over the wealth path, built on immutable per-period ledger records with retained execution details, and the reference accounting engine (`portlearn.ledger`).
+- Trading and cost accounting: cost-aware transaction and turnover accounting with proportional cost models (`portlearn.trades`, `portlearn.turnover`, `portlearn.costs`).
+- The strategy decision-contract seam: `Strategy.decide(context) -> DecisionResult` over `DecisionContext` — the decision-time aggregate of forecast, information, holdings, and strategy state — validated by `require_decision_result_compatible`.
 
 **Next**
 
@@ -55,7 +60,6 @@ PortLearn is under active research development. This roadmap is intentionally hi
 
 **Planned**
 
-- Portfolio construction and accounting.
 - Later deep-learning and reinforcement-learning research capabilities.
 
 Entries move forward on this roadmap as the underlying research foundation stabilizes; nothing here is a dated commitment.

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev2}/pyproject.toml

@@ -4,7 +4,7 @@
 # The distribution name and the PEP 440 version declared here are the single
 # version authority for the package.
 name = "portlearn"
-version = "0.0.1.dev1"
+version = "0.0.1.dev2"
 
 # Minimum supported Python; no untested upper-version exclusion.
 requires-python = ">=3.11"

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev2}/src/portlearn/__init__.py

@@ -18,18 +18,44 @@ from typing import Any
 
 __version__ = metadata.version("portlearn")
 
-__all__ = ["__version__", "data"]
+__all__ = ["__version__", "data", "weights"]
 
 
 def __getattr__(name: str) -> Any:
-    """Lazily import the ``data`` facade package (PEP 562), or fail."""
+    """Lazily import the public module facades (PEP 562)."""
     if name == "data":
         from importlib import import_module
 
         return import_module("portlearn.data")
+    if name == "weights":
+        from importlib import import_module
+
+        return import_module("portlearn.weights")
+    if name == "rebalance":
+        from importlib import import_module
+
+        return import_module("portlearn.rebalance")
+    if name == "trades":
+        from importlib import import_module
+
+        return import_module("portlearn.trades")
+    if name == "turnover":
+        from importlib import import_module
+
+        return import_module("portlearn.turnover")
+    if name == "costs":
+        from importlib import import_module
+
+        return import_module("portlearn.costs")
+    if name == "ledger":
+        from importlib import import_module
+
+        return import_module("portlearn.ledger")
     raise AttributeError(
         f"module {__name__!r} has no attribute {name!r}; the lazily "
-        "exposed public subpackage is 'data'."
+        "exposed public subpackage is 'data'; the public modules are "
+        "'weights', 'rebalance', 'trades', 'turnover', 'costs', and "
+        "'ledger'."
     )
 
 

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev2}/src/portlearn/alignment.py

@@ -1,23 +1,19 @@
 """Availability-aware alignment of mixed-frequency observations.
 
 This module implements the alignment laws as a thin composition
-surface over the frozen observation, timing, and period-calendar
-laws: an immutable
+surface over the observation, timing, and period-calendar laws: an immutable
 :class:`ObservationStore` indexed by ``(series_id, observation_time)``
-group, a single visibility query that delegates vintage selection to
-the frozen ``vintage_as_of`` operation, an :func:`align` output of the
+group, a single visibility query that delegates vintage selection to the ``vintage_as_of`` operation, an :func:`align` output of the
 caller's own vintage records, exactly one convenience month-end
 decision-calendar builder composed over the shared period-calendar
-substrate, and one grid-chronology validator reusing the frozen
-chronology and timestamp errors.
+substrate, and one grid-chronology validator reusing the chronology and timestamp errors defined in ``portlearn.timing``.
 
 The laws, in summary:
 
 - **Alignment is admission, parameterized by availability.** The only
   question a decision instant asks of any series — daily, monthly, or
   quarterly — is *what was knowable at this instant?* Visibility is
-  decided by each record's own declared ``available_time`` through the
-  frozen vintage operation and the frozen inclusive admission law;
+  decided by each record's own declared ``available_time`` through the ``vintage_as_of`` operation and the inclusive admission rule;
   this module never re-implements admission, never selects among
   vintages of one observation, and contains no date-matching or
   calendar-proximity join of any kind.
@@ -28,8 +24,7 @@ The laws, in summary:
 - **The decision calendar is input, not machinery.** Alignment
   consumes one aware instant; decision grids are researcher inputs.
   One convenience builder ships — month-end instants through the
-  shared substrate — and nothing else; schedule machinery is a named,
-  deferred seam owned elsewhere.
+  shared substrate — and nothing else; schedule machinery is not provided here.
 - **No aggregation, no resampling, no implicit publication lag.**
   Alignment aligns; frequency transformation and bounded carry-forward
   belong to the transforms module and are composed by the researcher,
@@ -38,8 +33,8 @@ The laws, in summary:
   assumes none, and cannot be configured with one.
 - **Chronology of the grid.** Calendar-builder output and any
   researcher-supplied grid must be strictly increasing aware instants;
-  non-monotone grids reject with the frozen chronology error, and
-  naive instants reject with the frozen timestamp error at every entry
+  non-monotone grids reject with ``InvalidChronologyError``, and
+  naive instants reject with ``NaiveTimestampError`` at every entry
   point.
 
 **RESEARCHER WARNING — align on availability, never on dates.**
@@ -104,8 +99,7 @@ class GridDeclarationError(ValueError):
     Raised for malformed calendar declarations (bad year/month/count
     shapes), malformed request elements, and grids that are not
     non-empty sequences of entries. Chronology violations and naive
-    instants are not declaration failures — they reject with the
-    frozen chronology and timestamp errors respectively.
+    instants are not declaration failures — they reject with ``InvalidChronologyError`` and ``NaiveTimestampError`` respectively.
     """
 
 
@@ -121,7 +115,7 @@ class ObservationStore:
     """An immutable point-in-time index over declared observations.
 
     Built from :class:`~portlearn.observations.TimedObservation`
-    records under the frozen record discipline: every record's own
+    records under the record rules: every record's own
     constructor laws apply (aware instants, mandatory availability,
     availability never preceding the observation), and two records
     sharing the full identity triple ``(series_id, observation_time,
@@ -129,7 +123,7 @@ class ObservationStore:
     last-write-wins, no value-equality exception. A revision — the
     same observation with a later ``available_time`` — is a separate
     record and is exactly what the store holds; selecting among
-    vintages of one observation is the frozen vintage operation's job
+    vintages of one observation is the ``vintage_as_of`` operation's job
     at query time, never the store's at build time.
 
     The index maps each ``(series_id, observation_time)`` group to its
@@ -207,7 +201,7 @@ class ObservationStore:
     def _visible_group_record(
         self, key: tuple[str, datetime], decision: datetime
     ) -> TimedObservation | None:
-        """The frozen vintage operation's answer for one group."""
+        """The ``vintage_as_of`` operation's answer for one group."""
         visible = vintage_as_of(self._groups[key], decision)
         if visible is not None:
             return visible
@@ -234,9 +228,7 @@ class ObservationStore:
 
         For each requested series identifier, in request order, the
         latest of its observation groups that has a visible vintage at
-        ``decision_instant`` — selected by issuing the frozen
-        ``vintage_as_of`` operation per group and admitting by the
-        frozen inclusive law (``available_time <= decision_instant``).
+        ``decision_instant`` — selected by issuing ``vintage_as_of`` per group and admitting by the inclusive rule (``available_time <= decision_instant``).
         A series with no visible vintage at the instant answers
         ``None`` in its slot: explicit absence, not an error, not an
         imputation, and never a silently carried stale value. The
@@ -328,7 +320,7 @@ def align(
     """The admissible vintage records for one decision instant.
 
     For each requested ``(series_id, observation_time)`` group, in
-    request order, the frozen vintage operation's visible vintage at
+    request order, the ``vintage_as_of`` operation's visible vintage at
     ``decision_instant`` (the latest ``available_time`` at or before
     the instant — availability exactly at the decision admits). A
     group with no visible vintage contributes no record: explicit
@@ -337,8 +329,7 @@ def align(
     order with absence removed — and holds the store's own record
     objects.
 
-    The output is the caller's to submit to the frozen
-    ``InformationSet(items, as_of=decision_instant)`` constructor for
+    The output is the caller's to submit to the ``InformationSet(items, as_of=decision_instant)`` constructor for
     fail-closed admission; this function never constructs an
     information set and never bypasses its constructor laws.
 
@@ -387,9 +378,7 @@ def require_increasing_instants(grid: Iterable[Any]) -> None:
     builder emits — must be a non-empty sequence of aware instants in
     strictly increasing order: a decision calendar that repeats or
     reverses an instant is malformed. Equal adjacent instants reject
-    (strict increase); a non-monotone grid rejects with the frozen
-    ``InvalidChronologyError``; a naive entry rejects with the frozen
-    ``NaiveTimestampError``; a non-sequence, a string, or an empty
+    (strict increase); a non-monotone grid rejects with ``InvalidChronologyError``; a naive entry rejects with ``NaiveTimestampError``; a non-sequence, a string, or an empty
     grid rejects with ``GridDeclarationError``. Comparisons use
     normalized instants, so equal instants expressed in different
     timezones still reject as equal. Returns ``None`` on success.
@@ -476,14 +465,11 @@ def monthly_decision_calendar(
     calendar day, leap February included) in the declared timezone
     ``tz``, UTC-normalized at storage. The period-end mapping is the
     substrate's, imported here and never restated; no quarterly,
-    weekly, or custom-frequency builder ships, and no schedule
-    machinery exists in this module (that seam is named and owned
-    elsewhere).
+    weekly, or custom-frequency builder ships, and no schedule machinery exists in this module.
 
     ``tz`` must be an aware timezone object — a naive or invalid zone
-    rejects fail-closed with ``NaiveTimestampError`` through the
-    substrate's own law; no default zone is ever assumed. The builder's
-    output is validated by the same grid law researchers' grids obey
+    rejects fail-closed with ``NaiveTimestampError`` through the substrate's own validation; no default zone is ever assumed. The builder's
+    output is validated by the same grid rule researchers' grids obey
     (:func:`require_increasing_instants`) before it is returned, so
     every calendar this module emits is strictly increasing aware
     instants by construction. ``SAME_INSTANT`` availability under this

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev2}/src/portlearn/calendar.py

@@ -1,7 +1,6 @@
 """Period-calendar substrate: the period-end → aware-instant mapping.
 
-This module implements, exactly once, the period-calendar convention
-frozen here: a month-end or
+This module implements, exactly once, the period-calendar convention: a month-end or
 quarter-end calendar day maps to the **last instant of that period in a
 declared timezone** — ``23:59:59.999999`` on the last calendar day of
 the period, expressed in the declared zone, then UTC-normalized at
@@ -11,10 +10,6 @@ It is a neutral substrate:
 
 - **stdlib-only** (``calendar``/``datetime`` arithmetic, no providers);
 - **pure** — same inputs, equal instants, no state;
-- **frozen-law-abiding** — every produced instant constructs through
-  :func:`portlearn.timing.to_instant`, so a naive or invalid declared
-  timezone rejects fail-closed with ``NaiveTimestampError`` exactly as
-  every other time input does;
 - **disciplined** — it defines no contract errors, imports from
   ``portlearn.timing`` only, and knows nothing about ingestion,
   adapters, alignment, or schedules.  Consumers import these helpers;
@@ -41,13 +36,13 @@ def _period_end_instant(year: int, month: int, tzinfo: Any) -> datetime:
     """The last instant of ``month`` in ``year`` under declared ``tzinfo``.
 
     Builds ``23:59:59.999999`` on the month's last calendar day in the
-    declared zone and UTC-normalizes it through the frozen
-    ``to_instant`` law, which also rejects a naive/invalid zone
+    declared zone and UTC-normalizes it through
+    ``to_instant``, which also rejects a naive/invalid zone
     fail-closed.
     """
     last_day = _calendar.monthrange(year, month)[1]
     # A deliberately naive wall-clock reading: the declared zone is attached
-    # on the next line and the frozen law then UTC-normalizes the result.
+    # on the next line and to_instant then UTC-normalizes the result.
     wall = datetime(  # noqa: DTZ001 — zone attached immediately below
         year, month, last_day, *_LAST_TIME_OF_DAY
     )
@@ -72,7 +67,7 @@ def quarter_end_instant(year: int, quarter: int, tzinfo: Any) -> datetime:
     ``quarter`` is 1–4; the quarter's closing month is March, June,
     September, or December.  Returns the UTC-normalized instant of
     ``23:59:59.999999`` on that month's last calendar day in ``tzinfo``,
-    with the same fail-closed timezone law as
+    with the same fail-closed timezone check as
     :func:`month_end_instant`.
     """
     if not isinstance(quarter, int) or isinstance(quarter, bool):

portlearn-0.0.1.dev2/src/portlearn/costs.py

@@ -0,0 +1,276 @@
+"""Proportional transaction costs, convention-bound and fail-closed.
+
+This module defines the proportional cost model: the
+standard linear cost model ``Proportional(rate, turnover=...)`` bound
+to a **named turnover convention**, because a rate statement such as
+"25 bps transaction cost" is incomplete unless the library also
+records whether the rate applies to ``one_way`` or ``two_sided``
+turnover. The convention is a first-class binding input — a bare
+scalar turnover without a named convention is an incomplete cost
+specification.
+
+The laws, in summary:
+
+- **Convention binding.** The keyword is exactly ``turnover`` (never
+  alternated publicly with ``turnover_convention``) and accepts only
+  PortLearn's two recognized turnover conventions,
+  ``portlearn.turnover.one_way`` and
+  ``portlearn.turnover.two_sided``; arbitrary lambdas or unknown
+  callables reject fail-closed. Internally the model preserves a
+  stable canonical identity — ``"one_way"`` / ``"two_sided"`` — so
+  future experiment provenance (e.g. YAML ``costs: {model:
+  proportional, rate: 0.0025, turnover: one_way}``) can represent the
+  convention without redesigning the public API. No registries, no
+  plugin machinery: the two conventions of the turnover module are
+  the only selectable measures.
+- **Cost fraction and factor.** ``q = rate ×
+  selected_turnover_measure(trade)`` and ``F_cost = 1 − q``; the
+  domain is ``0 ≤ q < 1``, enforced fail-closed on non-finite,
+  negative, or ``q ≥ 1`` inputs (``F_cost = 0`` or negative is not a
+  lawful portfolio state). The domain check is the safety net
+  especially for leveraged/short books, whose two-sided turnover may
+  exceed 2 and push ``q`` to 1 even at moderate rates.
+- **Rate law.** ``rate ≥ 0`` real finite; negative, non-real
+  (``bool``/``Decimal``/string/complex), and non-finite rates reject;
+  ``rate = 0`` is lawful (the frictionless model).
+- **Baseline cost-to-weights separation.** Under this declared
+  simplified baseline convention: weights track — ``POST_TRADE =
+  TARGET`` exactly, the rebalancing law unaltered; value track
+  — multiplied by ``F_cost``. Costs multiply value, never weights.
+  Cash financing, execution-level fee funding, partial fills,
+  spreads, slippage, market impact, and share-space execution are
+  outside this baseline and would alter it. The model is timeless:
+  no execution-timestamp binding, accounting-period assignment,
+  ledger row placement, or wealth path (downstream execution
+  accounting owns those).
+- **Composition and purity.** Over a trade sequence the total cost
+  factor is ``F_cost,total = Π_k F_cost,k``, and where a growth basis
+  is needed ``G_after_cost = G_before_cost × F_cost,total``; no
+  ``r_net`` return-record form is defined here. Models are pure with
+  respect to the trade: evaluating ``q``/``f_cost`` never mutates or
+  consumes it, so one stored trade can be evaluated under many cost
+  models (rates 0.0010/0.0025/0.0050, say) without rerunning the
+  optimizer.
+
+The error surface is ``ValueError`` only (plus ``TypeError`` for a
+missing required constructor argument); numerics follow the
+checked-real discipline.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from typing import Any
+
+from portlearn import turnover as _turnover
+from portlearn.trades import WeightTrade, from_weights
+from portlearn.weights import PortfolioWeights, WeightState
+
+__all__ = ["Proportional"]
+
+# The closed convention registry of record: the two named measures of
+# the turnover module, keyed by their canonical identity strings. No
+# plugin machinery — this fixed mapping is the entire selectable set.
+_RECOGNIZED_CONVENTIONS: dict[str, Any] = {
+    "one_way": _turnover.one_way,
+    "two_sided": _turnover.two_sided,
+}
+
+
+def _require_rate(value: object) -> float:
+    """The rate law: a finite real ≥ 0; ``bool`` is not a number; no
+    clipping or normalization — out-of-domain inputs reject."""
+    if isinstance(value, bool):
+        raise ValueError(  # noqa: TRY004 — bool rejection is law, not type discipline
+            f"rate must be a real number, not bool; got {value!r}"
+        )
+    if not isinstance(value, (int, float)):
+        raise ValueError(  # noqa: TRY004 — ValueError-only surface is the error law
+            f"rate must be a real number; got {type(value).__name__}: "
+            f"{value!r}. Use float(rate)."
+        )
+    try:
+        converted = float(value)
+    except OverflowError:
+        converted = math.inf
+    if not math.isfinite(converted):
+        raise ValueError(f"rate must be finite; got {value!r}")
+    if converted < 0.0:
+        raise ValueError(f"rate must be nonnegative; got {converted!r}")
+    return converted
+
+
+def _require_recognized_convention(value: object) -> tuple[str, Any]:
+    """Only PortLearn's two named turnover conventions are selectable;
+    arbitrary lambdas/callables/scalars reject fail-closed."""
+    for identity, measure in _RECOGNIZED_CONVENTIONS.items():
+        if value is measure:
+            return identity, measure
+    raise ValueError(
+        "the turnover convention must be one of PortLearn's recognized "
+        f"named conventions (portlearn.turnover.one_way or "
+        f"portlearn.turnover.two_sided); got {value!r}. A bare scalar or "
+        "arbitrary callable is an incomplete cost specification and "
+        "fails closed."
+    )
+
+
+def _require_weight_mapping(value: object, role: str) -> Mapping[str, float]:
+    """A weight book operand must be a mapping of identifiers to
+    weights; anything else rejects fail-closed on the ValueError-only
+    surface before book construction is attempted."""
+    if not isinstance(value, Mapping):
+        raise ValueError(  # noqa: TRY004 — ValueError-only surface is the error law
+            f"the {role} weights must be a mapping of asset identifiers "
+            f"to weights; got {type(value).__name__}: {value!r}"
+        )
+    return value
+
+
+class Proportional:
+    """The convention-bound proportional cost model.
+
+    Public shape: constructor ``Proportional(rate,
+    turnover)`` — both required, the keyword name exactly ``turnover``;
+    public read attributes ``rate: float`` and ``convention: str`` (the
+    stable canonical identity ``"one_way"``/``"two_sided"``); methods
+    ``q(trade) -> float``, ``f_cost(trade) -> float``, and
+    ``estimate_trade_cost(pre_trade_weights, target_weights) -> float``
+    (the public ``CostModel`` protocol surface: it builds the same
+    canonical ``WeightTrade`` from the two weight mappings —
+    ``PRE_TRADE`` and ``TARGET`` books under the same validation —
+    and returns ``q`` of it, with no duplicated turnover arithmetic).
+    Immutable
+    from the instant it exists; pure with respect to every trade it
+    evaluates.
+    """
+
+    __slots__ = ("_convention", "_measure", "_rate")
+
+    def __init__(self, rate: object, turnover: object) -> None:
+        # Both inputs are first-class binding inputs: neither may be
+        # omitted — a bare rate is as incomplete as a missing one.
+        # (A missing argument is Python's own TypeError; an explicitly
+        # supplied non-convention rejects as a ValueError domain
+        # failure below, keeping the domain error surface ValueError-only.)
+        checked_rate = _require_rate(rate)
+        identity, measure = _require_recognized_convention(turnover)
+        object.__setattr__(self, "_rate", checked_rate)
+        object.__setattr__(self, "_convention", identity)
+        object.__setattr__(self, "_measure", measure)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        raise AttributeError(
+            f"{type(self).__name__} is an immutable value object; "
+            f"attribute {name!r} cannot be assigned"
+        )
+
+    def __delattr__(self, name: str) -> None:
+        raise AttributeError(
+            f"{type(self).__name__} is an immutable value object; "
+            f"attribute {name!r} cannot be deleted"
+        )
+
+    @property
+    def rate(self) -> float:
+        """The nonnegative finite real proportional rate."""
+        return self._rate
+
+    @property
+    def convention(self) -> str:
+        """The stable canonical convention identity string."""
+        return self._convention
+
+    def q(self, trade: WeightTrade) -> float:
+        """The cost fraction ``q = rate × turnover_measure(trade)``.
+
+        Fail-closed on the domain ``0 ≤ q < 1``: a non-finite,
+        negative, or ``q ≥ 1`` result rejects — ``F_cost = 0`` or
+        negative is not a lawful portfolio state, and leveraged books
+        can reach the boundary even at moderate rates. Pure with
+        respect to the trade.
+        """
+        measure_q = self._checked_measure(trade)
+        fraction = self._rate * measure_q
+        if not math.isfinite(fraction):
+            raise ValueError(
+                f"the cost fraction q must be finite; got {fraction!r} "
+                f"(rate {self._rate!r} × {self._convention} turnover "
+                f"{measure_q!r})"
+            )
+        if fraction < 0.0:
+            raise ValueError(
+                f"the cost fraction q must be nonnegative; got {fraction!r}"
+            )
+        if fraction >= 1.0:
+            raise ValueError(
+                f"the cost fraction q must satisfy q < 1 (F_cost > 0); "
+                f"got q = {fraction!r} (rate {self._rate!r} × "
+                f"{self._convention} turnover {measure_q!r}) — F_cost = 0 "
+                "or negative is not a lawful portfolio state and fails "
+                "closed."
+            )
+        return fraction
+
+    def f_cost(self, trade: WeightTrade) -> float:
+        """The cost factor ``F_cost = 1 − q`` on the domain ``0 <
+        F_cost ≤ 1``; identical fail-closed domain enforcement."""
+        return 1.0 - self.q(trade)
+
+    def estimate_trade_cost(
+        self,
+        pre_trade_weights: Mapping[str, float],
+        target_weights: Mapping[str, float],
+    ) -> float:
+        """Estimate the cost of trading to the target weight book.
+
+        The public ``CostModel`` surface over raw weight mappings:
+        constructs the canonical ``WeightTrade`` with exactly the
+        ``from_weights`` semantics (books validated as ``PRE_TRADE``
+        and ``TARGET``, deltas over the union of assets) and returns
+        ``q`` of that trade — the bound convention is applied through
+        the canonical path, with no turnover arithmetic duplicated
+        here. Fail-closed domain enforcement is therefore identical
+        to ``q``'s.
+        """
+        trade = from_weights(
+            PortfolioWeights(
+                _require_weight_mapping(pre_trade_weights, "pre-trade"),
+                WeightState.PRE_TRADE,
+            ),
+            PortfolioWeights(
+                _require_weight_mapping(target_weights, "target"),
+                WeightState.TARGET,
+            ),
+        )
+        return self.q(trade)
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}(rate={self._rate!r}, "
+            f"turnover={self._convention!r})"
+        )
+
+    def _checked_measure(self, trade: WeightTrade) -> float:
+        """The bound convention evaluated on the trade, fail-closed on
+        non-finite turnover intermediates (ValueError-only surface)."""
+        if not isinstance(trade, WeightTrade):
+            raise ValueError(  # noqa: TRY004 — ValueError-only surface is the error law
+                "the cost model operates on a WeightTrade value object; "
+                f"got {type(trade).__name__}: {trade!r}. Construct one "
+                "with portlearn.trades.from_weights(pre_trade, target)."
+            )
+        measured = self._measure(trade)
+        if not math.isfinite(measured):
+            raise ValueError(
+                f"the {self._convention} turnover must be finite; got "
+                f"{measured!r} — a non-finite turnover intermediate is "
+                "undefined and fails closed."
+            )
+        if measured < 0.0:
+            raise ValueError(
+                f"the {self._convention} turnover must be nonnegative; "
+                f"got {measured!r}"
+            )
+        return measured

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev2}/src/portlearn/data/__init__.py

@@ -21,9 +21,8 @@ def __getattr__(name: str) -> Any:
     """Lazily import one public name, or fail with the module error.
 
     ``ResearchDataset`` — the provider-neutral sealed two-state
-    container — imports lazily like the provider facades, so the
-    package's import side-effect laws hold exactly as before: a bare
-    ``import portlearn.data`` still registers this package alone (the
+    container — imports lazily like the provider facades, preserving the package's import side-effect guarantees: a bare
+    ``import portlearn.data`` registers this package alone (the
     dataset module, and with it pandas, loads only on first use).  The
     state types (``UnqualifiedDataset``/``QualifiedDataset``) stay
     internal to :mod:`portlearn.data.dataset`.  The diagnostics