axis-synome 0.1.0.dev63__tar.gz → 0.1.0.dev65__tar.gz

{axis_synome-0.1.0.dev63/src/axis_synome.egg-info → axis_synome-0.1.0.dev65}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.0.dev63
+Version: 0.1.0.dev65
 Summary: Axis specification modules (entities, formulas, validators)
 Author-email: Archon Tech <hello@archontech.ai>
 License: MIT
@@ -86,6 +86,27 @@ Or use as a flake8 plugin:
 flake8 --select=AXS your_spec.py
 ```
 
+## Examples
+
+Runnable examples that show how to navigate the entity graph (assets,
+tokens, networks, protocols of a prime) live under
+[`examples/`](./examples/README.md). Run any of them with:
+
+```bash
+uv run python examples/02_assets_and_tokens_of_a_prime.py
+```
+
+Highlights:
+
+- `01_prime_basics.py` — basic facts about each `PrimeAgent`.
+- `02_assets_and_tokens_of_a_prime.py` — list assets, tokens, underlying
+  tokens, and group by network/protocol.
+- `03_inverse_lookups.py` — *which primes hold token X?*, *which primes are
+  on network Y?*, *which prime owns this address?*
+- `04_atlas_provenance.py` — trace each asset back to its Atlas document.
+- `05_feeding_a_formula.py` — bridge external records into `Position`s and
+  call `asc(...)`.
+
 ## About
 
 `axis-synome` is a specification framework for defining financial and risk calculations in DeFi, with emphasis on formalized, auditable spec files.

{axis_synome-0.1.0.dev63 → axis_synome-0.1.0.dev65}/README.md

@@ -71,6 +71,27 @@ Or use as a flake8 plugin:
 flake8 --select=AXS your_spec.py
 ```
 
+## Examples
+
+Runnable examples that show how to navigate the entity graph (assets,
+tokens, networks, protocols of a prime) live under
+[`examples/`](./examples/README.md). Run any of them with:
+
+```bash
+uv run python examples/02_assets_and_tokens_of_a_prime.py
+```
+
+Highlights:
+
+- `01_prime_basics.py` — basic facts about each `PrimeAgent`.
+- `02_assets_and_tokens_of_a_prime.py` — list assets, tokens, underlying
+  tokens, and group by network/protocol.
+- `03_inverse_lookups.py` — *which primes hold token X?*, *which primes are
+  on network Y?*, *which prime owns this address?*
+- `04_atlas_provenance.py` — trace each asset back to its Atlas document.
+- `05_feeding_a_formula.py` — bridge external records into `Position`s and
+  call `asc(...)`.
+
 ## About
 
 `axis-synome` is a specification framework for defining financial and risk calculations in DeFi, with emphasis on formalized, auditable spec files.

axis_synome-0.1.0.dev65/examples/01_prime_basics.py

@@ -0,0 +1,31 @@
+# ruff: noqa: T201
+# Examples are runnable scripts; printing is the whole point.
+"""Example 01 — Basic facts about a Prime.
+
+A ``PrimeAgent`` is an enum whose ``.value`` is a ``PrimeAgentData`` dataclass
+carrying the operational facts of a Sky Star Agent (prime): its name, the
+assets it controls, the networks it operates on, its PSM protocols, and a
+few ASC-specific knobs.
+
+This example walks every prime and prints those facts.
+"""
+
+from axis_synome.spec.asc.entities.primes import PrimeAgent
+
+
+def main() -> None:
+    for prime in PrimeAgent:
+        data = prime.value
+        print(f"=== {data.name} ===")
+        print(f"  asc_exempt              : {data.asc_exempt}")
+        print(f"  # assets                : {len(data.assets)}")
+        print(f"  networks                : {sorted(n.value for n in data.networks)}")
+        print(f"  psm_protocols           : {sorted(p.value for p in data.psm_protocols)}")
+        print(f"  alm_proxy               : {data.alm_proxy.value if data.alm_proxy else None}")
+        print(f"  max_pct_latent_asc      : {data.max_pct_latent_asc}")
+        print(f"  min_pct_asc_of_collat   : {data.min_pct_asc_of_collateral}")
+        print()
+
+
+if __name__ == "__main__":
+    main()

axis_synome-0.1.0.dev65/examples/02_assets_and_tokens_of_a_prime.py

@@ -0,0 +1,77 @@
+# ruff: noqa: T201
+"""Example 02 — Find the assets and tokens associated with a prime.
+
+This is the headline question: *"What does Spark hold?"*
+
+It demonstrates several useful projections off ``PrimeAgentData.assets``:
+
+* the raw list of ``Asset`` rows,
+* the set of ``Token`` symbols held (e.g. ``USDC``, ``sUSDe``, ...),
+* the set of *underlying* tokens (the real economic exposure behind a
+  wrapped/yield-bearing asset),
+* assets grouped by ``Network``,
+* assets grouped by ``Protocol``.
+
+All of this is pure attribute access on the entity graph — no I/O, no
+external lookups.
+"""
+
+from collections import defaultdict
+
+from axis_synome.spec.asc.entities.assets import Asset
+from axis_synome.spec.asc.entities.networks import Network
+from axis_synome.spec.asc.entities.primes import PrimeAgent
+from axis_synome.spec.asc.entities.protocol_sets import Protocol
+
+
+def show_assets_for(prime: PrimeAgent) -> None:
+    data = prime.value
+    print(f"=== {data.name} ===")
+    print(f"Total assets: {len(data.assets)}\n")
+
+    # 1. Direct list of assets.
+    print("Assets (token @ protocol on network):")
+    for asset in data.assets:
+        print(f"  - {asset.token.value:<20} @ {asset.protocol.value:<35} on {asset.network.value}")
+    print()
+
+    # 2. Set of tokens held.
+    tokens_held = {a.token for a in data.assets}
+    print(f"Distinct tokens held ({len(tokens_held)}):")
+    print("  " + ", ".join(sorted(t.value for t in tokens_held)))
+    print()
+
+    # 3. Set of underlying tokens (real economic exposure).
+    underlying = {a.underlying_asset for a in data.assets}
+    print(f"Distinct underlying tokens ({len(underlying)}):")
+    print("  " + ", ".join(sorted(t.value for t in underlying)))
+    print()
+
+    # 4. Group by network.
+    by_network: dict[Network, list[Asset]] = defaultdict(list)
+    for a in data.assets:
+        by_network[a.network].append(a)
+    print("Assets grouped by network:")
+    for network in sorted(by_network, key=lambda n: n.value):
+        tokens = sorted(a.token.value for a in by_network[network])
+        print(f"  {network.value:<20} ({len(tokens)}): {', '.join(tokens)}")
+    print()
+
+    # 5. Group by protocol.
+    by_protocol: dict[Protocol, list[Asset]] = defaultdict(list)
+    for a in data.assets:
+        by_protocol[a.protocol].append(a)
+    print("Assets grouped by protocol:")
+    for protocol in sorted(by_protocol, key=lambda p: p.value):
+        tokens = sorted(a.token.value for a in by_protocol[protocol])
+        print(f"  {protocol.value:<40} ({len(tokens)}): {', '.join(tokens)}")
+    print()
+
+
+def main() -> None:
+    show_assets_for(PrimeAgent.SPARK)
+    show_assets_for(PrimeAgent.GROVE)
+
+
+if __name__ == "__main__":
+    main()

axis_synome-0.1.0.dev65/examples/03_inverse_lookups.py

@@ -0,0 +1,85 @@
+# ruff: noqa: T201
+"""Example 03 — Inverse lookups across the entity graph.
+
+The previous examples ask "given a prime, what does it hold?". This file
+goes the other direction:
+
+* Given a ``Token``, which primes hold it (and via which protocol/network)?
+* Given a ``Network``, which primes operate on it?
+* Given an EVM address, which prime owns the matching asset?
+
+These queries are simple comprehensions over ``PrimeAgent`` and its
+``.value.assets`` list.
+"""
+
+from axis_synome.spec.asc.entities.networks import Network
+from axis_synome.spec.asc.entities.primes import PrimeAgent
+from axis_synome.spec.asc.entities.tokens import Token
+from axis_synome.spec_support.evm_address import EvmAddress
+
+
+def primes_holding_token(token: Token) -> list[tuple[PrimeAgent, list[str]]]:
+    """Return ``(prime, [contexts])`` pairs for every prime holding ``token``.
+
+    ``contexts`` strings have the form ``"<protocol> on <network>"``.
+    """
+    matches: list[tuple[PrimeAgent, list[str]]] = []
+    for prime in PrimeAgent:
+        contexts: list[str] = [
+            f"{a.protocol.value} on {a.network.value}"
+            for a in prime.value.assets
+            if a.token == token
+        ]
+        if contexts:
+            matches.append((prime, contexts))
+    return matches
+
+
+def primes_on_network(network: Network) -> list[PrimeAgent]:
+    return [p for p in PrimeAgent if network in p.value.networks]
+
+
+def prime_owning_address(address: EvmAddress) -> tuple[PrimeAgent, str] | None:
+    for prime in PrimeAgent:
+        for asset in prime.value.assets:
+            if asset.address == address:
+                return prime, asset.token.value
+    return None
+
+
+def main() -> None:
+    print("=== Primes holding USDC ===")
+    for prime, contexts in primes_holding_token(Token.USDC):
+        print(f"  {prime.value.name}:")
+        for ctx in contexts:
+            print(f"    - {ctx}")
+    print()
+
+    print("=== Primes holding JAAA ===")
+    for prime, contexts in primes_holding_token(Token.JAAA):
+        print(f"  {prime.value.name}: {', '.join(contexts)}")
+    print()
+
+    print("=== Primes operating on Base ===")
+    for prime in primes_on_network(Network.BASE):
+        print(f"  - {prime.value.name}")
+    print()
+
+    print("=== Primes operating on Avalanche ===")
+    for prime in primes_on_network(Network.AVALANCHE):
+        print(f"  - {prime.value.name}")
+    print()
+
+    # Reverse lookup by EVM address — pick a real one from Grove's JAAA holding.
+    probe = EvmAddress("0x1121F4e21eD8B9BC1BB9A2952cDD8639aC897784")
+    print(f"=== Owner of address {probe} ===")
+    hit = prime_owning_address(probe)
+    if hit is None:
+        print("  (no match)")
+    else:
+        prime, token_name = hit
+        print(f"  {prime.value.name} (token: {token_name})")
+
+
+if __name__ == "__main__":
+    main()

axis_synome-0.1.0.dev65/examples/04_atlas_provenance.py

@@ -0,0 +1,36 @@
+# ruff: noqa: T201
+"""Example 04 — Atlas provenance for every asset.
+
+Every ``Asset`` carries two ``source`` strings: ``source`` (the Atlas
+document number defining the wrapped/listed asset) and
+``underlying_asset_source`` (the document defining the underlying token).
+These are dot-separated identifiers like ``A.6.1.1.2.2.6.1.3.2.1.2.2.2.1``
+that resolve to documents under ``content/`` (validated by the
+``check-spec-uuids`` make target).
+
+This example prints the provenance trail for each asset of a prime, so a
+reviewer can jump straight from the spec entity to the Atlas document that
+authorizes it.
+"""
+
+from axis_synome.spec.asc.entities.primes import PrimeAgent
+
+
+def show_provenance(prime: PrimeAgent) -> None:
+    print(f"=== {prime.value.name} — asset provenance ===")
+    for asset in prime.value.assets:
+        print(f"  {asset.token.value} on {asset.network.value} via {asset.protocol.value}")
+        print(f"    address                  : {asset.address}")
+        print(f"    Atlas doc (asset)        : {asset.source}")
+        print(f"    underlying token         : {asset.underlying_asset.value}")
+        print(f"    underlying address       : {asset.underlying_asset_address}")
+        print(f"    Atlas doc (underlying)   : {asset.underlying_asset_source}")
+        print()
+
+
+def main() -> None:
+    show_provenance(PrimeAgent.GROVE)
+
+
+if __name__ == "__main__":
+    main()

axis_synome-0.1.0.dev65/examples/05_feeding_a_formula.py

@@ -0,0 +1,91 @@
+# ruff: noqa: T201
+"""Example 05 — Bridge external records into Positions and call a formula.
+
+Once you know the *associated concepts* of a prime (examples 02 and 03),
+the next step is feeding real-world holdings into a formula. This example
+shows the canonical bridge pattern:
+
+1. External data arrives as plain dicts (API response, CSV row, DB record).
+2. ``record_to_position`` resolves token/protocol/network strings to enums
+   and builds ``Asset`` + ``Position`` instances.
+3. We hand the resulting ``list[Position]`` to ``asc(...)`` to get a USD total.
+
+The bridge intentionally lives outside the spec subset (which forbids I/O
+and string→enum coercion). Only the formulas it feeds into are constrained.
+
+Note: ``asc(...)`` requires the ``axis-synome[runtime]`` extra (numpy-backed
+``ReferenceSpecRuntime``). It is installed in this repo's dev environment.
+"""
+
+from axis_synome.spec.asc.entities.asset_categories import AssetCategory
+from axis_synome.spec.asc.entities.assets import Asset
+from axis_synome.spec.asc.entities.networks import Network
+from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
+from axis_synome.spec.asc.entities.protocol_sets import Protocol
+from axis_synome.spec.asc.entities.tokens import Token
+from axis_synome.spec.asc.entities.types import Position
+from axis_synome.spec.asc.formulas.asc import asc
+from axis_synome.spec_support.evm_address import EvmAddress
+
+# A single placeholder address; real callers would pass the on-chain address
+# of the holding (e.g., the LitePSM, the Curve pool, the Aave aToken, ...).
+MOCK_ADDRESS = EvmAddress("0x1121F4e21eD8B9BC1BB9A2952cDD8639aC897784")
+
+
+def record_to_position(rec: dict) -> Position:
+    """Convert a raw record dict to a ``Position``.
+
+    Required keys: ``token``, ``protocol``, ``network``, ``value_usd``.
+    Optional keys: ``pool_paired_with_usds``, ``fee_tier``.
+    """
+    return Position(
+        asset=Asset(
+            token=Token(rec["token"]),
+            protocol=Protocol(rec["protocol"]),
+            network=Network(rec["network"]),
+            address=MOCK_ADDRESS,
+            underlying_asset=Token(rec["token"]),
+            underlying_asset_address=MOCK_ADDRESS,
+            underlying_asset_source="",
+            categories={AssetCategory.CASH_STABLECOIN},
+        ),
+        value_usd=float(rec["value_usd"]),
+        pool_paired_with_usds=rec.get("pool_paired_with_usds"),
+        fee_tier=rec.get("fee_tier"),
+    )
+
+
+def main() -> None:
+    # Pretend these came from an indexer or a CSV.
+    api_records = [
+        {
+            "token": "USDC",
+            "protocol": "LitePSM",
+            "network": "Ethereum Mainnet",
+            "value_usd": 500_000.0,
+        },
+        {"token": "USDC", "protocol": "PSM3", "network": "Base", "value_usd": 250_000.0},
+        {
+            "token": "USDC",
+            "protocol": "Curve",
+            "network": "Ethereum Mainnet",
+            "value_usd": 300_000.0,
+            "pool_paired_with_usds": True,
+        },
+    ]
+
+    positions = [record_to_position(r) for r in api_records]
+
+    print(f"Built {len(positions)} positions from external records:")
+    for p in positions:
+        print(
+            f"  - {p.asset.token.value:<6} via {p.asset.protocol.value:<10} "
+            f"on {p.asset.network.value:<18} = ${p.value_usd:,.2f}"
+        )
+
+    total_asc = asc(EligiblePrimeAgentASC.SPARK, positions)
+    print(f"\nasc(SPARK, positions) = ${total_asc:,.2f}")
+
+
+if __name__ == "__main__":
+    main()

axis_synome-0.1.0.dev65/examples/README.md

@@ -0,0 +1,58 @@
+# axis-synome examples
+
+Runnable, self-contained scripts that show how to navigate the entity graph
+exposed by `axis_synome.spec` — answering questions like *"what assets does
+Spark hold?"*, *"which primes operate on Base?"*, or *"which Atlas document
+defines this token?"*.
+
+## Overview
+
+The examples are numbered by complexity. Earlier ones introduce the core
+entities; later ones build on them to do reverse lookups, surface Atlas
+provenance, and bridge external data into a real formula call.
+
+Each file is a plain Python script with a module docstring describing what
+it shows and a `main()` that prints to stdout. They use only public imports
+under `axis_synome.spec.asc.entities` and `axis_synome.spec.asc.formulas`,
+and are exercised on every CI run by `tests/axis_synome/test_examples.py`,
+so they cannot silently rot.
+
+Run any of them directly:
+
+```bash
+cd axis-synome
+uv run python examples/02_assets_and_tokens_of_a_prime.py
+```
+
+| File | Question it answers |
+| --- | --- |
+| `01_prime_basics.py` | What does a `PrimeAgent` carry (name, networks, PSM protocols, asset count)? |
+| `02_assets_and_tokens_of_a_prime.py` | Which `Asset`s and `Token`s does a given prime hold, grouped by network and protocol? |
+| `03_inverse_lookups.py` | Which primes hold a given token? Which primes operate on a given network? Which prime owns an address? |
+| `04_atlas_provenance.py` | Which Atlas document defines each asset and its underlying token? |
+| `05_feeding_a_formula.py` | How do I bridge external records (API/CSV/DB rows) into `Position`s and call `asc(...)`? |
+
+## Running specific spec formulas
+
+For end-to-end usage of individual formulas — how to construct the
+expected entity inputs, what the outputs look like, and how to bridge
+external records into the call — read the formula tests under
+`tests/axis_synome/`. They double as worked examples and are the
+authoritative reference for how each formula is meant to be called:
+
+- `tests/axis_synome/asc/test_asc.py` — `asc(prime, positions)` end-to-end,
+  including a bridge from an API-shaped `dict` into `Position`s
+  (`test_bridge_from_api_response`).
+- `tests/axis_synome/asc/test_resting_asc.py`,
+  `test_latent_asc.py`, `test_ratio_latent_asc.py`,
+  `test_asc_collateral_ratio.py`, `test_asc_incentive.py`, `test_dab.py` —
+  one file per ASC sub-formula, each showing the smallest realistic input
+  set that exercises the formula.
+- `tests/axis_synome/asc/mocks.py` — shared fixtures (`spark_resting_positions()`,
+  `spark_latent_positions()`, …) you can copy when building inputs.
+- `tests/axis_synome/suraf/formulas/test_scoring.py`,
+  `tests/axis_synome/suraf/formulas/test_crr.py` — same pattern for the
+  SURAF scoring / collateral-risk-rating formulas.
+
+When adding a new formula, add a `test_<formula>.py` next to the existing
+ones; that test then becomes the worked example for callers.

{axis_synome-0.1.0.dev63 → axis_synome-0.1.0.dev65}/pyproject.toml

@@ -25,6 +25,7 @@ Repository = "https://github.com/archon-research/next-gen-atlas"
 Documentation = "https://github.com/archon-research/next-gen-atlas"
 
 [project.scripts]
+axis-spec-inspect = "axis_synome.spec_inspect.cli:main"
 export_entities = "axis_synome.export_entities:main"
 
 [project.entry-points."flake8.extension"]

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

axis_synome-0.1.0.dev65/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.dev65/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.dev65/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.dev65/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
+    )