axis-synome 0.1.0.dev64__tar.gz → 0.1.0.dev66__tar.gz

{axis_synome-0.1.0.dev64/src/axis_synome.egg-info → axis_synome-0.1.0.dev66}/PKG-INFO

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

{axis_synome-0.1.0.dev64 → axis_synome-0.1.0.dev66}/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.dev64'
-__version_tuple__ = version_tuple = (0, 1, 0, 'dev64')
+__version__ = version = '0.1.0.dev66'
+__version_tuple__ = version_tuple = (0, 1, 0, 'dev66')
 
 __commit_id__ = commit_id = None

axis_synome-0.1.0.dev66/src/axis_synome/spec/entities/capital_types.py

@@ -0,0 +1,73 @@
+"""Capital structure types for the Risk Capital framework.
+
+Dataclasses modelling the capital structure of a Prime Agent as defined
+in Atlas A.3.2.1.2.2. These are interface types for the risk capital
+formulas — concrete instances are supplied at evaluation time, not
+defined here.
+
+The capital stack has two layers ordered by loss-absorption seniority:
+
+    1. Junior Risk Capital (JRC) — first to absorb losses.
+    2. Senior Risk Capital (SRC) — absorbs losses only after 100 % of
+       JRC has been wiped out.
+
+Each layer is further broken down by source (internal vs. external).
+The sourcing ratios (EPI, SPJ) constrain how much external and senior
+capital a Prime can count, ensuring sufficient "skin in the game".
+"""
+
+from axis_synome.spec_support.validated_dataclass import validated_dataclass
+
+
+@validated_dataclass
+class JuniorRiskCapital:
+    """Breakdown of a Prime Agent's Junior Risk Capital by source.
+
+    JRC is the first capital to absorb losses on investments made through
+    the Allocation System. It must experience 100 % losses before any
+    Senior Risk Capital is touched.
+
+    Attributes:
+        ijrc:  Internal Junior Risk Capital — capital owned by the Prime
+               Agent itself, held in its designated treasury (e.g. SubProxy).
+               IJRC is the foundation of the Prime's risk capacity: it
+               dictates the max EJRC via the EPI ratio, provides the
+               primary SPJ enablement for SRC, and bears the initial
+               Tip loss.
+        sejrc: Prime-External Junior Risk Capital — JRC rented from
+               another Prime via the JRC Rental Primitive. The capital
+               remains in the lender's treasury but counts towards the
+               borrower's JRC.
+        tejrc: Tokenized External Junior Risk Capital — capital provided
+               by external depositors into the TEJRC smart contract,
+               from which Primes can encumber funds.
+
+    :source_uuid: 92e51a94-ef70-4a86-9946-36077ebad1e9
+    """
+
+    ijrc: float
+    sejrc: float
+    tejrc: float
+
+
+@validated_dataclass
+class SeniorRiskCapital:
+    """Breakdown of a Prime Agent's Senior Risk Capital by source.
+
+    SRC is protected relative to JRC in the loss waterfall: it only
+    begins to absorb losses after JRC has been fully depleted, and then
+    absorbs 100 % of further losses. SRC can be originated from Sky
+    Core monthly or rented between Primes.
+
+    Attributes:
+        isrc: Internal Senior Risk Capital — provided from Sky Core's
+              Surplus Buffer.
+        esrc: External Senior Risk Capital — provided by users depositing
+              sUSDS into the srUSDS contract in exchange for higher
+              returns.
+
+    :source_uuid: 6bba2076-5d5b-43fd-82c6-df6a35f67355
+    """
+
+    isrc: float
+    esrc: float

axis_synome-0.1.0.dev66/src/axis_synome/spec/entities/risk_categories.py

@@ -0,0 +1,77 @@
+"""Risk category types for the Allocation System.
+
+Types representing the RRC component structure and instance-level status
+used across Instance and Aggregate RRC computations (A.3.2.1.1).
+"""
+
+from enum import Enum
+
+from axis_synome.spec_support.validated_dataclass import validated_dataclass
+
+
+class InstanceStatus(Enum):
+    """Operational status of an Allocation System Primitive Instance.
+
+    Every Instance has exactly one of these statuses at any time. Only
+    Active instances contribute to Aggregate RRC (A.3.2.1.1.2).
+
+    :source_uuid: 6aed5cc1-9671-4b73-88a9-fdd86ac93ece
+    """
+
+    ACTIVE = "Active"
+    SUSPENDED = "Suspended"
+    COMPLETED = "Completed"
+
+
+@validated_dataclass
+class InstanceRRCComponents:
+    """Three Required Risk Capital components for a single Instance.
+
+    Instance Total RRC = Financial RRC + Smart Contract RRC + Administrative RRC.
+
+    If any component cannot be calculated (represented as ``None``), the
+    Atlas mandates a conservative fallback (A.3.2.1.1.3.2): the Instance
+    Total RRC defaults to 100 % of invested capital.
+
+    Attributes:
+        financial_rrc:      RRC covering credit, market, and liquidity
+                            risk. Computed by asset-class-specific risk
+                            models under A.3.2.2.1.1.
+        smart_contract_rrc: RRC covering the risk of loss due to a bug
+                            or technical exploit in the invested protocol
+                            or its dependencies. Computed under A.3.2.2.1.2.
+        administrative_rrc: RRC covering the risk of loss due to abuse
+                            of privileged access (e.g. multisig) to the
+                            invested protocol. Computed under A.3.2.2.1.3.
+
+    :source_uuid: 5fe6b54c-cc68-4f8a-8d1e-5044af941afe
+    :source_uuid: 268af0e9-be3d-458e-9ccd-5a560abc7540
+    """
+
+    # TEMPORARY SCAFFOLDING: float | None fields are interim pending a future
+    # consolidation of A.3.2.1 and A.3.2.2. Do not copy this nullable pattern.
+    financial_rrc: float | None
+    smart_contract_rrc: float | None
+    administrative_rrc: float | None
+
+
+@validated_dataclass
+class AllocationSystemInstance:
+    """Single instance of the Allocation System Primitive.
+
+    Wraps the RRC components together with the instance's operational
+    status and invested capital, so that formulas can filter by status
+    explicitly — mirroring the Atlas rule that only Active instances
+    contribute to Aggregate RRC.
+
+    Attributes:
+        status:           Operational status. Only ``ACTIVE`` instances
+                          are included in the Aggregate RRC summation.
+        components:       The three RRC sub-components for this Instance.
+        invested_capital: Capital from Sky's Collateral Portfolio invested
+                          in this Instance, in USDS.
+    """
+
+    status: InstanceStatus
+    components: InstanceRRCComponents
+    invested_capital: float

axis_synome-0.1.0.dev66/src/axis_synome/spec/risk_capital/__init__.py

@@ -0,0 +1,21 @@
+"""Risk Capital specification.
+
+This package implements the computable rules for the Risk Capital
+framework, covering both the conceptual framework (A.3.2.1) and the
+detailed risk models (A.3.2.2).
+
+Conceptual framework (A.3.2.1):
+    - instance_rrc:         Per-instance RRC computation (demand side)
+    - aggregate_rrc:        Sum across active instances
+    - total_risk_capital:   TRC computation (supply side)
+    - capital_composition:  EPI/SPJ sourcing ratio constraints and constants
+    - jrc_loss_allocation:  Loss waterfall (Tip, pro-rata, SRC layers)
+
+Implementation (A.3.2.2):
+    - lindy_factor:         Shared Lindy adjustment factor
+    - audit_factor:         Audit risk factor
+    - financial_rrc/:       Per-asset-class Financial RRC models
+    - smart_contract_rrc/:  Smart Contract RRC models
+    - administrative_rrc/:  Administrative RRC models
+    - formulas/:            Asset-class-specific formula composition
+"""

axis_synome-0.1.0.dev66/src/axis_synome/spec/risk_capital/aggregate_rrc.py

@@ -0,0 +1,34 @@
+"""Aggregate Required Risk Capital.
+
+Sum Instance RRC across all Active instances of the Allocation System
+Primitive to determine the Prime Agent's total capital requirement.
+"""
+
+from axis_synome.spec.entities.risk_categories import (
+    AllocationSystemInstance,
+    InstanceStatus,
+)
+from axis_synome.spec.risk_capital.instance_rrc import instance_total_rrc
+
+
+def aggregate_rrc(
+    instances: list[AllocationSystemInstance],
+) -> float:
+    """Aggregate Required Risk Capital for a Prime Agent.
+
+    The Aggregate RRC is the sum of Instance Total RRC for each Active
+    Instance of the Allocation System Primitive that the Prime Agent has
+    deployed. Suspended and Completed instances are excluded.
+
+    The filtering is performed inside the formula: callers pass all
+    known instances and the Atlas eligibility rule is applied here,
+    following the same pattern as ``EligiblePrimeAgentASC`` filtering
+    in ASC formulas.
+
+    :source_uuid: 6aed5cc1-9671-4b73-88a9-fdd86ac93ece
+    """
+    return sum(
+        instance_total_rrc(inst.components, inst.invested_capital)
+        for inst in instances
+        if inst.status == InstanceStatus.ACTIVE
+    )

axis_synome-0.1.0.dev66/src/axis_synome/spec/risk_capital/capital_composition.py

@@ -0,0 +1,189 @@
+"""EPI/SPJ checks and Capital Composition rules.
+
+Two sourcing-ratio constraints ensure sufficient "skin in the game":
+
+    1. EPI (External Per Internal) — caps the total EJRC a Prime can
+       source based on its own IJRC (A.3.2.1.2.3.1.1).
+    2. SPJ (Senior Per Junior) — determines how much SRC each unit of
+       JRC can "enable". SPJ capacity can alternatively be diverted to
+       source additional EJRC at SPJ = 0 (A.3.2.1.2.3.1.2 and
+       A.3.2.1.2.3.1.2.1).
+
+The ratios are applied sequentially per A.3.2.1.2.3.2:
+
+    Step 1  EPI sets the initial EJRC ceiling from IJRC alone.
+    Step 2  SPJ capacity is computed from the resulting JRC pool.
+    Step 3  The Prime allocates SPJ capacity between enabling SRC and/or
+            sourcing additional non-SPJ-bearing EJRC.
+
+Parameter values (SPJ ratios, EPI ratio, Tip percentage) come from the
+A.3.2.2.2 implementation parameters and are cited individually.
+"""
+
+from typing import Final
+
+from axis_synome.spec.entities.capital_types import (
+    JuniorRiskCapital,
+    SeniorRiskCapital,
+)
+
+# ── SPJ ratios (A.3.2.2.2.2.2) ──────────────────────────────────────
+
+SPJ_IJRC: Final[float] = 1.00
+"""SPJ multiplier for Internal Junior Risk Capital.
+
+:source_uuid: 8578e240-3fe8-41c0-8b2c-15ec9a7181ab
+"""
+
+SPJ_SEJRC: Final[float] = 0.75
+"""SPJ multiplier for EPI-acquired Prime External Junior Risk Capital.
+
+:source_uuid: 8578e240-3fe8-41c0-8b2c-15ec9a7181ab
+"""
+
+SPJ_TEJRC: Final[float] = 0.50
+"""SPJ multiplier for EPI-acquired Tokenized External Junior Risk Capital.
+
+:source_uuid: 8578e240-3fe8-41c0-8b2c-15ec9a7181ab
+"""
+
+# ── EPI ratio (A.3.2.2.2.2.1) ───────────────────────────────────────
+
+EPI_RATIO: Final[float] = 1.00
+"""External Per Internal ratio cap for EJRC sourcing.
+
+:source_uuid: 3ed32706-c072-42b5-b1e5-187bddf8dc37
+"""
+
+# ── Tip JRC percentage (A.3.2.2.2.1.1) ─────────────────────────────
+
+TIP_JRC_PCT: Final[float] = 0.10
+"""Tip percentage of total JRC absorbed first by IJRC.
+
+:source_uuid: 73f2410b-3579-4c68-ae36-e4a4713a6e4b
+"""
+
+
+# ── EPI ratio checks (A.3.2.1.2.3.1.1) ─────────────────────────────
+
+
+def total_ejrc(
+    jrc: JuniorRiskCapital,
+) -> float:
+    """Total External JRC — the portion not owned by the Prime itself.
+
+    This is the quantity constrained by the EPI ratio: it must not
+    exceed EPI * IJRC.
+
+    :source_uuid: 57b0b226-ae2c-4d47-871d-57e6d3bb1a9f
+    """
+    return jrc.sejrc + jrc.tejrc
+
+
+def max_ejrc_from_epi(
+    ijrc: float,
+) -> float:
+    """EJRC ceiling imposed by the EPI ratio.
+
+    The External Per Internal ratio is the primary constraint ensuring a
+    baseline level of the Prime's own capital backs its external JRC
+    sourcing::
+
+        max EJRC = EPI * IJRC
+
+    :source_uuid: ff374833-920c-40f6-ae6c-a71d33d99b82
+    """
+    return EPI_RATIO * ijrc
+
+
+def epi_constraint_satisfied(
+    jrc: JuniorRiskCapital,
+) -> bool:
+    """True when the Prime's external JRC stays within the EPI limit.
+
+    True iff ``(SEJRC + TEJRC) <= EPI * IJRC``.
+
+    :source_uuid: ff374833-920c-40f6-ae6c-a71d33d99b82
+    """
+    ejrc: float = total_ejrc(jrc)
+    ceiling: float = max_ejrc_from_epi(jrc.ijrc)
+    return ejrc <= ceiling
+
+
+# ── SPJ ratio (A.3.2.1.2.3.1.2) ────────────────────────────────────
+
+
+def spj_capacity(
+    jrc: JuniorRiskCapital,
+) -> float:
+    """Total SPJ capacity from the Prime's JRC pool.
+
+    Each JRC type has a distinct SPJ multiplier reflecting its quality
+    as a loss buffer. Total SPJ capacity determines how much SRC the
+    Prime can "enable" (or, alternatively, how much extra non-SPJ-bearing
+    EJRC it can source via A.3.2.1.2.3.1.2.1)::
+
+        SPJ_capacity = IJRC * SPJ_IJRC + SEJRC * SPJ_SEJRC + TEJRC * SPJ_TEJRC
+
+    Since SRC only absorbs losses after JRC is depleted, the enablement
+    mechanism validates that sufficient JRC backing exists before SRC is
+    counted as eligible capital.
+
+    :source_uuid: fbc9a273-d217-4d52-8b3e-b496580f27a2
+    """
+    ijrc_contribution: float = jrc.ijrc * SPJ_IJRC
+    sejrc_contribution: float = jrc.sejrc * SPJ_SEJRC
+    tejrc_contribution: float = jrc.tejrc * SPJ_TEJRC
+    return ijrc_contribution + sejrc_contribution + tejrc_contribution
+
+
+def total_src(
+    src: SeniorRiskCapital,
+) -> float:
+    """Total Senior Risk Capital held by the Prime: ISRC + ESRC.
+
+    SRC is the second-loss layer: it absorbs losses only after JRC is
+    fully depleted. This total reflects what the Prime holds, but only
+    the portion "enabled" by SPJ capacity actually counts towards TRC.
+
+    :source_uuid: 6bba2076-5d5b-43fd-82c6-df6a35f67355
+    """
+    return src.isrc + src.esrc
+
+
+def enabled_src(
+    spj_capacity_for_src: float,
+    src: SeniorRiskCapital,
+) -> float:
+    """Effective SRC that counts towards TRC.
+
+    A Prime may hold more SRC than its JRC can enable. Only the portion
+    backed by SPJ capacity is eligible — and even that is capped by what
+    the Prime actually holds::
+
+        enabled SRC = min(SPJ capacity allocated to SRC, total SRC held)
+
+    :source_uuid: fbc9a273-d217-4d52-8b3e-b496580f27a2
+    """
+    held: float = total_src(src)
+    return min(spj_capacity_for_src, held)
+
+
+# ── Alternative SPJ use (A.3.2.1.2.3.1.2.1) ────────────────────────
+
+
+def spj_allocation_valid(
+    spj_capacity_for_src: float,
+    spj_capacity_for_ejrc: float,
+    total_spj_capacity: float,
+) -> bool:
+    """True when the Prime's SPJ allocation does not exceed its capacity.
+
+    A Prime may split its SPJ capacity between two uses: enabling SRC
+    (standard) and sourcing additional EJRC (alternative). EJRC acquired
+    via the alternative use has SPJ = 0 permanently. Any capacity
+    allocated to one use cannot simultaneously be allocated to the other.
+
+    :source_uuid: 03029174-91b4-4974-af1e-52438556a70b
+    """
+    return spj_capacity_for_src + spj_capacity_for_ejrc <= total_spj_capacity