axis-synome 0.1.0.dev30__tar.gz → 0.1.0.dev32__tar.gz

{axis_synome-0.1.0.dev30 → axis_synome-0.1.0.dev32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev30
+Version: 0.1.0.dev32
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT

{axis_synome-0.1.0.dev30 → axis_synome-0.1.0.dev32}/src/axis_synome/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.0.dev30'
-__version_tuple__ = version_tuple = (0, 1, 0, 'dev30')
+__version__ = version = '0.1.0.dev32'
+__version_tuple__ = version_tuple = (0, 1, 0, 'dev32')
 
 __commit_id__ = commit_id = None

{axis_synome-0.1.0.dev30 → axis_synome-0.1.0.dev32}/src/axis_synome/spec/asc/entities/tokens.py

@@ -56,3 +56,7 @@ class Token(Enum):
 
 
 CASH_STABLECOINS = {Token.USDC, Token.USDS, Token.DAI, Token.USDT}
+
+DIRECT_ETHENA_TOKENS = {Token.USDE, Token.S_USDE}
+
+PENDLE_ETHENA_TOKENS = {Token.PT_USDE, Token.PT_S_USDE}

axis_synome-0.1.0.dev32/src/axis_synome/spec/asc/entities/types.py

@@ -0,0 +1,23 @@
+from axis_synome.spec.asc.entities.assets import Asset
+from axis_synome.spec_support.pendle_validation import validate_pendle_token_has_expiration
+from axis_synome.spec_support.validated_dataclass import validated_dataclass
+
+
+@validated_dataclass(validators=[validate_pendle_token_has_expiration])
+class Position:
+    """A single holding of a token in a protocol on a network.
+
+    This is the main computational unit for all ASC / DAB formulas.
+
+    ``pt_expiration_time`` is meaningful only for Pendle Ethena PT holdings
+    (PT-USDe / PT-sUSDe). The ``validate_pendle_token_has_expiration``
+    validator (wired via the decorator since the spec subset disallows
+    methods on dataclasses) enforces at construction time that Pendle tokens
+    carry a non-``None`` expiration and other tokens do not.
+    """
+
+    asset: Asset
+    value_usd: float
+    pool_paired_with_usds: bool | None = None
+    fee_tier: float | None = None
+    pt_expiration_time: int | None = None

axis_synome-0.1.0.dev32/src/axis_synome/spec/risk_capital/financial_rrc/__init__.py

@@ -0,0 +1,5 @@
+"""Instance Financial Required Risk Capital.
+
+Asset-class-specific risk models for computing the Financial RRC
+component of each Allocation System Instance.
+"""

axis_synome-0.1.0.dev32/src/axis_synome/spec/risk_capital/financial_rrc/entities.py

@@ -0,0 +1,35 @@
+"""Entities for Financial RRC perpetual-position deployment events."""
+
+from axis_synome.spec.asc.entities.primes import PrimeAgent
+from axis_synome.spec_support.validated_dataclass import validated_dataclass
+
+
+@validated_dataclass
+class RiskAdvisorApproval:
+    """Core Council Risk Advisor approval for a Superstate deployment."""
+
+    approved_amount_usds: float
+    approval_timestamp: int
+
+
+@validated_dataclass
+class SuperstateDeployment:
+    """A Prime Agent's capital deployment to Superstate (umbrella type)."""
+
+    agent: PrimeAgent
+    amount_usds: float
+
+
+@validated_dataclass
+class SuperstateInitialDeployment(SuperstateDeployment):
+    """A Prime Agent's first capital deployment to Superstate."""
+
+
+@validated_dataclass
+class SuperstateSubsequentDeployment(SuperstateDeployment):
+    """A Prime Agent's subsequent (post-first) Superstate deployment.
+
+    Each subsequent deployment requires explicit Risk Advisor approval.
+    """
+
+    approval: RiskAdvisorApproval

axis_synome-0.1.0.dev32/src/axis_synome/spec/risk_capital/financial_rrc/perpetual_positions.py

@@ -0,0 +1,507 @@
+"""Perpetual Positions Financial RRC — Near-Term Treatment.
+
+Near-term Instance Financial CRR rules for perpetual-position exposures.
+Covers Ethena (direct, indirect, Pendle) and Superstate (USCC) exposure
+types, their capital requirement ratios, aggregate exposure limits, and
+deployment limits.
+"""
+
+from enum import Enum
+from typing import Final, cast
+
+from axis_synome.spec.asc.entities.primes import PrimeAgent
+from axis_synome.spec.asc.entities.protocol_sets import Protocol
+from axis_synome.spec.asc.entities.tokens import (
+    DIRECT_ETHENA_TOKENS,
+    PENDLE_ETHENA_TOKENS,
+)
+from axis_synome.spec.asc.entities.types import Position
+from axis_synome.spec.risk_capital.financial_rrc.entities import (
+    SuperstateInitialDeployment,
+    SuperstateSubsequentDeployment,
+)
+
+# ---------------------------------------------------------------------------
+# Eligible Prime Agents for Ethena exposures
+# ---------------------------------------------------------------------------
+
+
+class EthenaEligiblePrimeAgent(Enum):
+    """Prime Agents eligible to hold Ethena exposures.
+
+    Membership derived from per-agent Ethena Exposure Limits: only agents
+    with a non-zero limit are included.
+
+    :source_uuid: 8e120edf-c87b-4d99-8f2a-65fb49bcc3b7
+    """
+
+    SPARK = PrimeAgent.SPARK.value
+    GROVE = PrimeAgent.GROVE.value
+
+
+# ---------------------------------------------------------------------------
+# Ethena CRR parameters
+# ---------------------------------------------------------------------------
+
+DIRECT_ETHENA_CRR: Final[float] = 0.03
+"""Instance Financial CRR for direct USDe and sUSDe holdings.
+
+:source_uuid: e0fa035c-e8f3-4cd2-8ca1-a6afbd1825eb
+"""
+
+# is required before these CRRs can be applied to typed positions.
+
+INDIRECT_ETHENA_ETHENA_COLLATERAL_CRR: Final[float] = 0.03
+"""Instance Financial CRR for Ethena-related assets lent against Ethena-related collateral.
+
+:source_uuid: cfa615fb-9927-4059-873a-7c824a517835
+"""
+
+INDIRECT_ETHENA_NON_ETHENA_COLLATERAL_CRR: Final[float] = 0.04
+"""Instance Financial CRR for non-Ethena assets lent against Ethena-related collateral.
+
+:source_uuid: dadc95a6-c8ef-4abb-b9a5-d51bf2c0bf29
+"""
+
+# ---------------------------------------------------------------------------
+# Pendle Ethena CRR parameters
+# ---------------------------------------------------------------------------
+
+PENDLE_ETHENA_INITIAL_CRR: Final[float] = 0.10
+"""Instance Financial CRR for Pendle Ethena exposures at exactly six months to maturity.
+
+:source_uuid: 5d2d2430-2fd5-4418-a688-e8f091eb44b9
+"""
+
+PENDLE_ETHENA_FINAL_CRR: Final[float] = DIRECT_ETHENA_CRR
+"""Instance Financial CRR at PT maturity, equal to the Direct Ethena Exposures CRR
+since the PT is convertible into the underlying asset.
+
+:source_uuid: 900ecd08-64b7-4f37-8539-f4e822f11d98
+"""
+
+PENDLE_ETHENA_MATURITY_THRESHOLD_SECONDS: Final[int] = 180 * 24 * 60 * 60
+"""Six-month maturity threshold in seconds (180 days).
+
+:source_uuid: 6ed19cc0-5447-4df9-a9c1-45c8730f5f44
+"""
+
+PENDLE_ETHENA_TOTAL_DECAY: Final[float] = PENDLE_ETHENA_INITIAL_CRR - PENDLE_ETHENA_FINAL_CRR
+"""Total CRR decay from initial value to final value over the six-month window.
+
+:source_uuid: c5530d25-b8ef-4ebe-9b38-7b2a29014ff3
+"""
+
+PENDLE_ETHENA_TOTAL_DURATION_SECONDS: Final[int] = PENDLE_ETHENA_MATURITY_THRESHOLD_SECONDS
+"""Duration in seconds of the time-decay window (six months).
+
+:source_uuid: 0e21a4c4-cd66-4ace-9dcd-6015fc9e4966
+"""
+
+PENDLE_ETHENA_DECAY_RATE_PER_SECOND: Final[float] = (
+    PENDLE_ETHENA_TOTAL_DECAY / PENDLE_ETHENA_TOTAL_DURATION_SECONDS
+)
+"""CRR decay rate per second over the six-month window.
+
+:source_uuid: cda560ff-5b25-44e1-bad4-e6ccfefdf7eb
+"""
+
+PENDLE_ETHENA_CONCENTRATION_LIMIT: Final[float] = 0.20
+"""Maximum fraction of total Allocation System Investments that may be in
+Pendle Ethena exposures before 100% CRR applies.
+
+:source_uuid: 6f850537-5e8a-4e57-95c8-f57a099ed8f3
+"""
+
+# ---------------------------------------------------------------------------
+# Superstate CRR parameters
+# ---------------------------------------------------------------------------
+
+SUPERSTATE_CRR: Final[float] = 0.045
+"""Instance Financial CRR for Superstate (USCC) exposures.
+
+:source_uuid: ffca1065-7f92-4815-8a65-52bdbc82c558
+"""
+
+# ---------------------------------------------------------------------------
+# Aggregate exposure limit parameters
+# ---------------------------------------------------------------------------
+
+ETHENA_AGGREGATE_EXPOSURE_LIMIT: Final[float] = 1_300_000_000.0
+"""Maximum Ethena Aggregate Exposure across all Prime Agents, in USDS.
+
+:source_uuid: 176c8562-848c-4868-8490-8e64da24adcd
+"""
+
+SUPERSTATE_AGGREGATE_EXPOSURE_LIMIT: Final[float] = 500_000_000.0
+"""Maximum Superstate Aggregate Exposure across all Prime Agents, in USDS.
+
+:source_uuid: ea606bf7-6dbf-41d2-a993-79b66c56b7c2
+"""
+
+# ---------------------------------------------------------------------------
+# Superstate deployment limit parameters
+# ---------------------------------------------------------------------------
+
+SUPERSTATE_INITIAL_DEPLOYMENT_LIMIT: Final[float] = 20_000_000.0
+"""Maximum first deployment of capital into Superstate exposures, in USDS.
+
+:source_uuid: 3fd57a2e-3e2a-41c1-a9f7-cfbe58799837
+"""
+
+SUPERSTATE_SUBSEQUENT_DEPLOYMENT_LIMIT: Final[float] = 50_000_000.0
+"""Maximum per-deployment amount for subsequent Superstate deployments, in USDS.
+Each subsequent deployment requires Core Council Risk Advisor approval.
+
+:source_uuid: e36d7537-95f8-4156-955f-bc74d37935d8
+"""
+
+
+# ---------------------------------------------------------------------------
+# Pendle Ethena CRR formulas
+# ---------------------------------------------------------------------------
+
+
+def pendle_ethena_crr_at_maturity_leq_six_months(
+    current_time: int,
+    start_time: int,
+) -> float:
+    """CRR = max(finalValue, initialValue - (currentTime - startTime) * decayRatePerSecond).
+
+    Clamped at the final CRR so a PT past expiration returns the at-maturity
+    value rather than a negative number.
+
+    :source_uuid: 6ed19cc0-5447-4df9-a9c1-45c8730f5f44
+    """
+    elapsed: int = current_time - start_time
+    return max(
+        PENDLE_ETHENA_FINAL_CRR,
+        PENDLE_ETHENA_INITIAL_CRR - (elapsed * PENDLE_ETHENA_DECAY_RATE_PER_SECOND),
+    )
+
+
+def pendle_ethena_crr(
+    current_time: int,
+    expiration_time: int,
+) -> float:
+    """Returns 1.0 (100% Instance Total CRR) when maturity exceeds six months,
+    otherwise the linearly decaying CRR.
+
+    :source_uuid: 4094c159-9132-454a-81be-361a461b5098
+    """
+    time_to_maturity: int = expiration_time - current_time
+    start_time: int = expiration_time - PENDLE_ETHENA_MATURITY_THRESHOLD_SECONDS
+    return (
+        1.0
+        if time_to_maturity > PENDLE_ETHENA_MATURITY_THRESHOLD_SECONDS
+        else pendle_ethena_crr_at_maturity_leq_six_months(current_time, start_time)
+    )
+
+
+# ---------------------------------------------------------------------------
+# Position classification predicates
+# ---------------------------------------------------------------------------
+
+
+def is_direct_ethena_position(
+    position: Position,
+) -> bool:
+    """True when the position's token is a direct Ethena token.
+
+    :source_uuid: e0fa035c-e8f3-4cd2-8ca1-a6afbd1825eb
+    """
+    return position.asset.token in DIRECT_ETHENA_TOKENS
+
+
+def is_pendle_ethena_position(
+    position: Position,
+) -> bool:
+    """True when the position's token is a Pendle Ethena token.
+
+    :source_uuid: 4094c159-9132-454a-81be-361a461b5098
+    """
+    return position.asset.token in PENDLE_ETHENA_TOKENS
+
+
+def is_ethena_position(
+    position: Position,
+) -> bool:
+    """True when the position is either a direct or a Pendle Ethena holding.
+
+    :source_uuid: 7ce05a43-e3ec-4c54-a11e-30e56526cfdd
+    """
+    return is_direct_ethena_position(position) or is_pendle_ethena_position(position)
+
+
+def is_superstate_position(
+    position: Position,
+) -> bool:
+    """True when the position's protocol is Superstate.
+
+    :source_uuid: ffca1065-7f92-4815-8a65-52bdbc82c558
+    """
+    return position.asset.protocol == Protocol.SUPERSTATE
+
+
+def is_recognised_perpetual_position(
+    position: Position,
+) -> bool:
+    """True when the position falls under one of the perpetual-position CRRs.
+
+    Defensive predicate for callers. The aggregator silently contributes 0
+    for positions that aren't recognised perpetual-position holdings (the
+    spec subset disallows ``raise`` in function bodies, so loud rejection
+    must happen caller-side); use ``all(map(is_recognised_perpetual_position, positions))``
+    on the input list before calling ``instance_perpetual_rrc_usd`` to catch
+    grouping errors.
+
+    :source_uuid: 69fac7fa-6168-4b74-99cc-28b557826556
+    """
+    return (
+        is_direct_ethena_position(position)
+        or is_pendle_ethena_position(position)
+        or is_superstate_position(position)
+    )
+
+
+# ---------------------------------------------------------------------------
+# Pendle Ethena portfolio CRR formulas
+# ---------------------------------------------------------------------------
+
+
+def pendle_ethena_aggregate_exposure(
+    pendle_positions: list[Position],
+) -> float:
+    """Sum of value_usd across all Pendle Ethena positions.
+
+    :source_uuid: 6f850537-5e8a-4e57-95c8-f57a099ed8f3
+    """
+    return sum(p.value_usd for p in pendle_positions)
+
+
+def pendle_ethena_concentration_breached(
+    pendle_positions: list[Position],
+    total_allocation_investments: float,
+) -> bool:
+    """True when Pendle Ethena exposure exceeds the concentration limit.
+
+    :source_uuid: 6f850537-5e8a-4e57-95c8-f57a099ed8f3
+    """
+    aggregate: float = pendle_ethena_aggregate_exposure(pendle_positions)
+    concentration: float = aggregate / total_allocation_investments
+    return concentration > PENDLE_ETHENA_CONCENTRATION_LIMIT
+
+
+def pendle_ethena_position_effective_crr(
+    position: Position,
+    pendle_positions: list[Position],
+    total_allocation_investments: float,
+    current_time: int,
+) -> float:
+    """Per-position Pendle Ethena CRR with portfolio-level concentration override.
+
+    Applies 100% Instance Total CRR if the portfolio concentration is breached;
+    otherwise returns the time-decay CRR for this position's expiration.
+
+    The ``cast(int, ...)`` at the read site narrows ``int | None`` to ``int``
+    for the type checker. This is safe because the ``Position`` validator
+    guarantees Pendle tokens carry a non-``None`` ``pt_expiration_time``; we
+    use ``cast`` rather than ``assert`` because the spec subset disallows
+    ``assert`` (see ``spec_validator/checker.py``).
+
+    :source_uuid: 6f850537-5e8a-4e57-95c8-f57a099ed8f3
+    """
+    breached: bool = pendle_ethena_concentration_breached(
+        pendle_positions, total_allocation_investments
+    )
+    base_crr: float = pendle_ethena_crr(current_time, cast(int, position.pt_expiration_time))
+    return 1.0 if breached else base_crr
+
+
+# ---------------------------------------------------------------------------
+# Aggregate exposure formulas
+# ---------------------------------------------------------------------------
+
+
+def ethena_exposure_limit(
+    _agent: EthenaEligiblePrimeAgent,
+) -> float:
+    """Each eligible Prime Agent receives one half of the aggregate limit.
+
+    :source_uuid: 8e120edf-c87b-4d99-8f2a-65fb49bcc3b7
+    """
+    return ETHENA_AGGREGATE_EXPOSURE_LIMIT / 2.0
+
+
+# ---------------------------------------------------------------------------
+# Boolean constraints — Ethena
+# ---------------------------------------------------------------------------
+
+
+def ethena_exposure(
+    positions: list[Position],
+) -> float:
+    """Sum of value_usd across all direct and Pendle Ethena positions.
+
+    :source_uuid: 642b6bee-9702-4339-bda3-3a35d025bbcc
+    """
+    return sum(p.value_usd for p in positions if is_ethena_position(p))
+
+
+def ethena_exposure_within_limit(
+    agent: EthenaEligiblePrimeAgent,
+    positions: list[Position],
+) -> bool:
+    """Constraint: agent's Ethena exposure must not exceed its limit.
+
+    No Prime Agent may make an investment that would cause its Ethena Exposures
+    to exceed its Ethena Exposure Limit.
+
+    :source_uuid: 50854ba8-c788-4df5-9c70-b6f070a28bfd
+    """
+    return ethena_exposure(positions) <= ethena_exposure_limit(agent)
+
+
+def ethena_aggregate_within_limit(
+    positions: list[Position],
+) -> bool:
+    """Constraint: total Ethena exposure across all Prime Agents.
+
+    Ethena Aggregate Exposure must not exceed the aggregate limit.
+
+    :source_uuid: 176c8562-848c-4868-8490-8e64da24adcd
+    """
+    return ethena_exposure(positions) <= ETHENA_AGGREGATE_EXPOSURE_LIMIT
+
+
+# ---------------------------------------------------------------------------
+# Boolean constraints — Superstate
+# ---------------------------------------------------------------------------
+
+
+def superstate_exposure(
+    positions: list[Position],
+) -> float:
+    """Sum of value_usd across all Superstate positions.
+
+    :source_uuid: 6cf2221f-214c-4bc2-8de1-b0d6adb2a327
+    """
+    return sum(p.value_usd for p in positions if is_superstate_position(p))
+
+
+def superstate_aggregate_within_limit(
+    positions: list[Position],
+) -> bool:
+    """Constraint: total Superstate exposure across all Prime Agents.
+
+    No Prime Agent may make an investment that would cause the Superstate
+    Aggregate Exposure to exceed the limit.
+
+    :source_uuid: a75e7eea-7567-4f5c-aba4-6d41fb6732dd
+    """
+    return superstate_exposure(positions) <= SUPERSTATE_AGGREGATE_EXPOSURE_LIMIT
+
+
+def superstate_initial_deployment_compliant(
+    deployment: SuperstateInitialDeployment,
+) -> bool:
+    """Constraint: a Prime Agent's first Superstate deployment.
+
+    Initial deployment into Superstate must not exceed the limit.
+
+    :source_uuid: 3fd57a2e-3e2a-41c1-a9f7-cfbe58799837
+    """
+    return deployment.amount_usds <= SUPERSTATE_INITIAL_DEPLOYMENT_LIMIT
+
+
+def superstate_subsequent_deployment_approved(
+    deployment: SuperstateSubsequentDeployment,
+) -> bool:
+    """Sub-predicate: approval covers the deployment amount.
+
+    :source_uuid: e36d7537-95f8-4156-955f-bc74d37935d8
+    """
+    return deployment.approval.approved_amount_usds >= deployment.amount_usds
+
+
+def superstate_subsequent_deployment_compliant(
+    deployment: SuperstateSubsequentDeployment,
+) -> bool:
+    """Constraint: each subsequent Superstate deployment by a Prime Agent.
+
+    Each subsequent Superstate deployment must not exceed the limit.
+    Additionally requires approval from the Core Council Risk Advisor.
+
+    :source_uuid: e36d7537-95f8-4156-955f-bc74d37935d8
+    """
+    return (
+        deployment.amount_usds <= SUPERSTATE_SUBSEQUENT_DEPLOYMENT_LIMIT
+        and superstate_subsequent_deployment_approved(deployment)
+    )
+
+
+# ---------------------------------------------------------------------------
+# Instance Financial RRC aggregator
+# ---------------------------------------------------------------------------
+
+
+def instance_perpetual_rrc_usd(
+    positions: list[Position],
+    portfolio: list[Position],
+    total_allocation_investments: float,
+    current_time: int,
+) -> float:
+    """Sum of per-category capital charges for perpetual-position exposures.
+
+    Signature follows the unified per-Instance contract proposed in
+    ``align_rrc.md`` §1: take everything needed for one Allocation Instance
+    and return one USD float.
+
+    Parameters:
+
+    - ``positions``: holdings in this Allocation Instance. The token /
+      ``pt_expiration_time`` invariant is enforced at ``Position`` construction
+      (see ``spec_support.pendle_validation``), so the misclassification cases
+      that previously needed runtime guards here can no longer reach this
+      function. Partition is by token predicate ``is_pendle_ethena_position``.
+    - ``portfolio``: reserved for future portfolio-context rules (e.g. rules
+      that look at non-Pendle holdings as portfolio context for perpetual-
+      position constraints). **Currently unused.** Included now for forward
+      compatibility with ``align_rrc.md`` §1 so the four RRC modules adopt a
+      common shape; the only portfolio-context check today is the Pendle
+      concentration limit, whose denominator is ``total_allocation_investments``
+      per Atlas A.3.2.2.1.1.1.2.1.1.1.3.3 ("their total Allocation System
+      Investments"), not a sum over ``portfolio``.
+    - ``total_allocation_investments``: the Prime Agent's total Allocation
+      System Investments, used as the Pendle concentration denominator.
+    - ``current_time``: reference timestamp (seconds) for Pendle time-decay.
+
+    The aggregator silently contributes 0 for any position that isn't a
+    recognised perpetual-position holding. The spec subset disallows
+    ``raise`` in function bodies, so loud rejection of caller-side grouping
+    errors lives in ``is_recognised_perpetual_position``: callers should run
+    ``all(map(is_recognised_perpetual_position, positions))`` before calling
+    this aggregator to catch non-perpetual holdings (USDC, ETH, lending
+    positions, etc.) that would otherwise silently dilute the charge.
+
+    :source_uuid: 69fac7fa-6168-4b74-99cc-28b557826556
+    """
+    _ = portfolio  # reserved for future portfolio-context rules; see docstring
+
+    pendle_subset: list[Position] = [p for p in positions if is_pendle_ethena_position(p)]
+    non_pendle_subset: list[Position] = [p for p in positions if not is_pendle_ethena_position(p)]
+
+    direct_charge: float = sum(
+        p.value_usd * DIRECT_ETHENA_CRR for p in non_pendle_subset if is_direct_ethena_position(p)
+    )
+    superstate_charge: float = sum(
+        p.value_usd * SUPERSTATE_CRR for p in non_pendle_subset if is_superstate_position(p)
+    )
+    pendle_charge: float = sum(
+        p.value_usd
+        * pendle_ethena_position_effective_crr(
+            p, pendle_subset, total_allocation_investments, current_time
+        )
+        for p in pendle_subset
+    )
+    return direct_charge + superstate_charge + pendle_charge

axis_synome-0.1.0.dev32/src/axis_synome/spec_support/pendle_validation.py

@@ -0,0 +1,52 @@
+"""Cross-field validator for Pendle Ethena tokens and pt_expiration_time.
+
+Pendle Ethena PT holdings (PT-USDe / PT-sUSDe) carry a fixed maturity, and the
+Instance Financial CRR for these holdings is a function of time-to-maturity
+(Atlas A.3.2.2.1.1.1.2.1.1.1.3.2). Other tokens have no concept of expiration.
+
+This helper enforces both directions of the constraint at construction time:
+
+- A Pendle Ethena token must carry a non-``None`` ``pt_expiration_time``.
+- A non-Pendle token must not carry a ``pt_expiration_time``.
+
+Catching this at ``Position`` construction (rather than at the perpetual-RRC
+aggregator) means a misclassification fails at the test or data-loading site,
+not deep inside the capital calculation where the symptom would be a silent
+0% CRR or a meaningless time-decay applied to an unrelated asset.
+
+Lives under ``spec_support`` rather than ``spec`` because it must be able to
+``raise`` (the spec subset / AXS plugin disallows ``raise`` in spec code) and
+because it is wired into ``Position`` via the ``validated_dataclass``
+decorator rather than as a method on the dataclass itself (the spec subset
+also disallows methods on dataclasses).
+"""
+
+from axis_synome.spec.asc.entities.tokens import PENDLE_ETHENA_TOKENS
+
+
+def validate_pendle_token_has_expiration(position) -> None:
+    """Enforce the token / pt_expiration_time invariant on a Position.
+
+    Raises ``ValueError`` if:
+
+    - ``position.asset.token`` is a Pendle Ethena token and
+      ``position.pt_expiration_time`` is ``None``.
+    - ``position.asset.token`` is not a Pendle Ethena token and
+      ``position.pt_expiration_time`` is set.
+    """
+    token = position.asset.token
+    pt_expiration_time = position.pt_expiration_time
+    is_pendle = token in PENDLE_ETHENA_TOKENS
+    has_expiration = pt_expiration_time is not None
+
+    if is_pendle and not has_expiration:
+        raise ValueError(
+            f"Pendle Ethena token {token} requires pt_expiration_time; "
+            "PT holdings carry a fixed maturity that the time-decay CRR depends on."
+        )
+    if not is_pendle and has_expiration:
+        raise ValueError(
+            f"Token {token} is not a Pendle Ethena token but pt_expiration_time "
+            f"is set to {pt_expiration_time}; pt_expiration_time is meaningful "
+            "only for PT-USDe / PT-sUSDe holdings."
+        )