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

axis_synome-0.1.0.dev63/AGENTS.md

@@ -0,0 +1,58 @@
+# axis-synome — Agent Instructions
+
+`axis-synome` is a Python framework that encodes Sky Atlas calculation rules as
+machine-verifiable specs. This file documents agent rules that apply when working
+inside `axis-synome/`.
+
+## Setup
+
+From the repo root, run **`make setup`** once after cloning. This installs Python
+deps, lefthook git hooks, and the Claude/Codex skills — all of which further guide
+and constrain agent work. Run **`make check-all`** before opening or updating a PR
+(it is what CI runs).
+
+## Where to find what
+
+- **`WRITING_SPECS.md`** — authoritative guide for writing axis-synome specs. Read
+  it before editing anything under `spec/`.
+
+## Editing axis-synome specs (`spec/`)
+
+Highlights from `WRITING_SPECS.md` that are not auto-discoverable from the code:
+
+- Specs are **pure, declarative Python**: no I/O, no mutable state, no side effects.
+- The spec language subset is enforced by the `AXS` flake8 plugin
+  (`axis_synome.spec_validator`); read its rules in `python_subset.py` and `checker.py`
+  rather than restating them here. In short: no reassignment, no conditional assignment,
+  no imperative control flow, no mutation, imports limited to the spec, `math`, and
+  approved support packages.
+- **Provenance lives in docstrings as reST fields**, e.g. `:source_uuid: <uuid>`. In
+  `**/formulas/*.py`, public functions are treated as formulas by convention; outside
+  formula modules, `:source_uuid:` is the explicit opt-in marker. Parameters are
+  module-level `Final[...]` constants with a trailing string-literal docstring carrying
+  the description and `:source_uuid:`. The `check-spec-uuids` tool resolves every
+  `:source_uuid:` against the `content/` document tree on every `make check-all`.
+- **Entities** use `pydantic.dataclasses.dataclass` (frozen) with closed-world `Enum`
+  fields; encode eligibility via Enum membership (e.g. `EligiblePrimeAgentASC`) rather
+  than booleans or runtime checks.
+- **Start entities formula-local** (`spec/<domain>/entities/`); only uplift to a shared
+  location when ≥3 independent formulas reuse them. Moving entities is a breaking
+  change.
+
+## Reviewing axis-synome PRs
+
+The shared review focus / non-focus list lives in
+[`../.github/copilot-instructions.md`](../.github/copilot-instructions.md) so Copilot
+and humans use the same list. Subtree-specific review rules for `axis-synome/**` live
+in
+[`../.github/instructions/axis-synome.instructions.md`](../.github/instructions/axis-synome.instructions.md)
+(in particular: spec-review patterns AXS cannot enforce, Atlas-alignment guidance,
+and the no-defensive-error-handling rule). Read both before reviewing.
+
+## What belongs in this AGENTS.md
+
+Only rules that an agent **cannot reasonably discover on its own** by reading the
+axis-synome subtree (e.g. `pyproject.toml`, the root `Makefile`, `lefthook.yml`).
+Things that *can* be discovered — make-target catalogues, dependency lists,
+type-checker choice, lint rule sets — drift out of date and belong in their config
+of origin, not here.

axis_synome-0.1.0.dev63/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

{axis_synome-0.1.0.dev61 → axis_synome-0.1.0.dev63}/PKG-INFO

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

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

{axis_synome-0.1.0.dev61 → axis_synome-0.1.0.dev63}/src/axis_synome/spec/asc/entities/tokens.py

@@ -56,14 +56,9 @@ class Token(Enum):
     WETH = "WETH"
 
 
-CASH_STABLECOINS = {Token.USDC, Token.USDS, Token.DAI, Token.USDT}
+CASH_STABLECOINS = {Token.USDC, Token.USDT, Token.PYUSD}
 """Tokens treated as Cash Stablecoins for ASC/DAB calculations.
 
-Note: The Atlas (A.3.3.2.1.3) currently defines Cash Stablecoins as
-USDC, USDT, and pyUSD. This constant differs (includes USDS and DAI;
-omits PYUSD) and the discrepancy should be reconciled — either by
-amending the Atlas or by updating this set.
-
 :source_uuid: 066a4d9f-13ed-4ac3-a55a-df7bf3429649
 """
 

{axis_synome-0.1.0.dev61 → axis_synome-0.1.0.dev63}/src/axis_synome/spec/asc/formulas/asc_collateral_ratio.py

@@ -1,4 +1,5 @@
 from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
+from axis_synome.spec.asc.entities.tokens import Token
 from axis_synome.spec.asc.entities.types import Position
 from axis_synome.spec.asc.formulas.latent_asc import latent_asc
 from axis_synome.spec.asc.formulas.resting_asc import resting_asc
@@ -7,13 +8,14 @@ from axis_synome.spec.asc.formulas.resting_asc import resting_asc
 def collateral_portfolio(
     positions: list[Position],
 ) -> float:
-    """Total Collateral Portfolio value for a prime: sum of all positions.
+    """Total capital deployed by the Prime Agent from Sky through the Allocation System, excluding USDS.
+
+    Positions are all assets the Prime has deployed via the Allocation System Primitive.
+    Any portion held in USDS is excluded per Atlas A.3.3.1.3.1.
 
     :source_uuid: 64e1390f-68a1-43ec-87a8-8ae7b990f7ec
-    :ambiguity: collateral_portfolio sums all positions including USDS — Atlas
-        A.3.3.1.3.1 explicitly excludes USDS from the Agent Collateral Portfolio.
     """
-    return sum(p.value_usd for p in positions)
+    return sum(p.value_usd for p in positions if p.asset.underlying_asset != Token.USDS)
 
 
 def asc_collateral_ratio(prime: EligiblePrimeAgentASC, positions: list[Position]) -> float:

{axis_synome-0.1.0.dev61 → axis_synome-0.1.0.dev63}/src/axis_synome/spec/asc/formulas/asc_incentive.py

@@ -1,5 +1,6 @@
 from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
 from axis_synome.spec.asc.entities.types import Position
+from axis_synome.spec.asc.formulas.asc_collateral_ratio import collateral_portfolio
 from axis_synome.spec.asc.formulas.latent_asc import latent_asc
 from axis_synome.spec.asc.formulas.resting_asc import resting_asc
 
@@ -12,11 +13,13 @@ def asc_incentive(
 ) -> float:
     """ASC incentive payment: eligible ASC times (base_rate - treasury_bill_rate).
 
+    Eligible ASC is the lesser of actual ASC and minimum required ASC.
+
     :source_uuid: 693330d6-9072-4054-bd61-d788537e34e8
-    :ambiguity: eligible_asc_usd = actual ASC with no min() cap — Atlas
-        A.3.3.2.2.4.1.1 defines Eligible ASC as the lesser of actual ASC and
-        Minimum ASC; the cap is absent, causing over-payment when actual ASC
-        exceeds the required minimum.
     """
-    eligible_asc_usd: float = resting_asc(positions) + latent_asc(prime, positions)
+    actual_asc_usd: float = resting_asc(positions) + latent_asc(prime, positions)
+    agent = prime.value
+    portfolio_usd: float = collateral_portfolio(positions)
+    minimum_required_asc_usd: float = portfolio_usd * agent.min_pct_asc_of_collateral
+    eligible_asc_usd: float = min(actual_asc_usd, minimum_required_asc_usd)
     return eligible_asc_usd * (base_rate - treasury_bill_rate)

axis_synome-0.1.0.dev63/src/axis_synome/spec/asc/formulas/dab.py

@@ -0,0 +1,25 @@
+from typing import Final
+
+from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
+from axis_synome.spec.asc.entities.types import Position
+from axis_synome.spec.asc.formulas.asc_collateral_ratio import collateral_portfolio
+
+DAB_REQUIRED_PCT: Final[float] = 0.25
+"""Required DAB as a fraction of minimum required ASC.
+
+:source_uuid: 1e129119-a2ce-4978-b235-c50f2a1c5e2e
+"""
+
+
+def dab_required(
+    prime: EligiblePrimeAgentASC,
+    positions: list[Position],
+) -> float:
+    """Required DAB: DAB_REQUIRED_PCT of minimum required ASC.
+
+    :source_uuid: 1e129119-a2ce-4978-b235-c50f2a1c5e2e
+    """
+    agent = prime.value
+    portfolio_usd: float = collateral_portfolio(positions)
+    minimum_required_asc_usd: float = portfolio_usd * agent.min_pct_asc_of_collateral
+    return minimum_required_asc_usd * DAB_REQUIRED_PCT

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

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

{axis_synome-0.1.0.dev61 → axis_synome-0.1.0.dev63}/src/axis_synome.egg-info/SOURCES.txt

@@ -1,4 +1,6 @@
 .flake8
+AGENTS.md
+CLAUDE.md
 README.md
 WRITING_SPECS.md
 pyproject.toml
@@ -15,7 +17,6 @@ src/axis_synome.egg-info/top_level.txt
 src/axis_synome/spec/__init__.py
 src/axis_synome/spec/all_entities/__init__.py
 src/axis_synome/spec/all_entities/lending_markets.py
-src/axis_synome/spec/asc/README.md
 src/axis_synome/spec/asc/entities/__init__.py
 src/axis_synome/spec/asc/entities/alm_proxies.py
 src/axis_synome/spec/asc/entities/asset_categories.py

{axis_synome-0.1.0.dev61 → axis_synome-0.1.0.dev63}/tests/axis_synome/asc/conftest.py

@@ -27,7 +27,7 @@ def spark_positions():
             "pool_paired_with_usds": True,
         },
         {
-            "token": "USDS",
+            "token": "USDT",
             "protocol": "Uniswap",
             "network": "Ethereum Mainnet",
             "value_usd": 250.0,
@@ -55,7 +55,7 @@ def spark_positions():
             "value_usd": 200.0,
         },
         {"token": "USDT", "protocol": "Aave", "network": "Ethereum Mainnet", "value_usd": 150.0},
-        {"token": "DAI", "protocol": "Morpho", "network": "Ethereum Mainnet", "value_usd": 300.0},
+        {"token": "PYUSD", "protocol": "Morpho", "network": "Ethereum Mainnet", "value_usd": 300.0},
     ]
     # Map as the second step: convert raw records into typed Position objects
     return mocks.positions_from_records(raw_data)

{axis_synome-0.1.0.dev61 → axis_synome-0.1.0.dev63}/tests/axis_synome/asc/mocks.py

@@ -37,7 +37,7 @@ def spark_resting_positions() -> list[Position]:
     - USDC in PSM3 on Arbitrum (L2 PSM) = 200.0
     - USDC in PSM3 on Base (L2 PSM) = 150.0
     - USDC in Curve paired with USDS = 300.0
-    - USDS in Uniswap paired with USDS = 250.0
+    - USDT in Uniswap paired with USDS = 250.0
     - USDC in GUNI at 0.01% fee tier = 400.0
                                 total = 1 400.0
     """
@@ -97,11 +97,11 @@ def spark_resting_positions() -> list[Position]:
         ),
         Position(
             asset=Asset(
-                token=Token.USDS,
+                token=Token.USDT,
                 protocol=Protocol.UNISWAP,
                 network=Network.ETHEREUM_MAINNET,
                 address=MOCK_ADDRESS,
-                underlying_asset=Token.USDS,
+                underlying_asset=Token.USDT,
                 underlying_asset_address=MOCK_ADDRESS,
                 underlying_asset_source="",
                 categories={AssetCategory.LENDING_MARKET},
@@ -133,7 +133,7 @@ def spark_latent_positions() -> list[Position]:
     - USDC in Curve NOT paired with USDS = 100.0
     - USDC in SparkLend (lending) = 200.0
     - USDT in Aave (lending) = 150.0
-    - DAI in Morpho (lending) = 300.0
+    - PYUSD in Morpho (lending) = 300.0
                             total = 750.0
     """
     return [
@@ -179,11 +179,11 @@ def spark_latent_positions() -> list[Position]:
         ),
         Position(
             asset=Asset(
-                token=Token.DAI,
+                token=Token.PYUSD,
                 protocol=Protocol.MORPHO,
                 network=Network.ETHEREUM_MAINNET,
                 address=MOCK_ADDRESS,
-                underlying_asset=Token.DAI,
+                underlying_asset=Token.PYUSD,
                 underlying_asset_address=MOCK_ADDRESS,
                 underlying_asset_source="",
                 categories={AssetCategory.LENDING_MARKET},

{axis_synome-0.1.0.dev61 → axis_synome-0.1.0.dev63}/tests/axis_synome/asc/test_asc_collateral_ratio.py

@@ -19,8 +19,8 @@ from .mocks import MOCK_ADDRESS, MOCK_CATEGORIES
 SPARK = EligiblePrimeAgentASC.SPARK
 
 
-def test_collateral_portfolio_sums_all_positions():
-    # Includes both ASC-qualifying and non-qualifying assets.
+def test_collateral_portfolio_excludes_usds():
+    # USDS position is excluded per Atlas A.3.3.1.3.1; non-USDS positions are summed.
     positions = [
         Position(
             asset=Asset(
@@ -48,6 +48,19 @@ def test_collateral_portfolio_sums_all_positions():
             ),
             value_usd=900.0,
         ),
+        Position(
+            asset=Asset(
+                token=Token.USDS,
+                protocol=Protocol.UNISWAP,
+                network=Network.ETHEREUM_MAINNET,
+                address=MOCK_ADDRESS,
+                underlying_asset=Token.USDS,
+                underlying_asset_address=MOCK_ADDRESS,
+                underlying_asset_source="",
+                categories=MOCK_CATEGORIES,
+            ),
+            value_usd=500.0,
+        ),
     ]
     assert collateral_portfolio(positions) == 1000.0
 

{axis_synome-0.1.0.dev61 → axis_synome-0.1.0.dev63}/tests/axis_synome/asc/test_asc_incentive.py

@@ -16,8 +16,9 @@ SPARK = EligiblePrimeAgentASC.SPARK
 
 
 def test_positive_incentive_when_base_above_tbill():
-    # asc=1000, base=0.05, tbill=0.03
-    # incentive = 1000*0.02 = 20
+    # portfolio=1000, min_required_asc = 1000*0.05 = 50
+    # actual_asc=1000 > min_required, so eligible=50
+    # incentive = 50*0.02 = 1.0
     positions = [
         Position(
             asset=Asset(
@@ -35,7 +36,7 @@ def test_positive_incentive_when_base_above_tbill():
     ]
     assert asc_incentive(
         SPARK, positions, base_rate=0.05, treasury_bill_rate=0.03
-    ) == pytest.approx(20.0)
+    ) == pytest.approx(1.0)
 
 
 def test_zero_incentive_when_rates_equal():
@@ -61,6 +62,8 @@ def test_zero_incentive_when_rates_equal():
 
 def test_negative_incentive_when_base_below_tbill():
     # Can occur when the treasury bill rate exceeds the base rate.
+    # eligible = min(actual_asc=1000, min_required=50) = 50
+    # incentive = 50*(0.03-0.05) = -1.0
     positions = [
         Position(
             asset=Asset(
@@ -78,7 +81,7 @@ def test_negative_incentive_when_base_below_tbill():
     ]
     assert asc_incentive(
         SPARK, positions, base_rate=0.03, treasury_bill_rate=0.05
-    ) == pytest.approx(-20.0)
+    ) == pytest.approx(-1.0)
 
 
 def test_incentive_scales_with_asc_amount():
@@ -122,11 +125,13 @@ def test_incentive_scales_with_asc_amount():
 def test_bridge_asc_incentive(spark_positions):
     """Shows asc_incentive against user-fetched positions.
 
-    asc=2150, base=0.05, tbill=0.03 // incentive = 2150*0.02 = 43.0
+    portfolio=2150, min_required_asc = 2150*0.05 = 107.5
+    actual_asc=2150 > min_required, so eligible=107.5
+    incentive = 107.5*0.02 = 2.15
 
     The rate parameters (base_rate, treasury_bill_rate) are supplied by the
     caller — they come from a separate governance or market data source,
     not from the position records.
     """
     result = asc_incentive(SPARK, spark_positions, base_rate=0.05, treasury_bill_rate=0.03)
-    assert result == pytest.approx(43.0)
+    assert result == pytest.approx(2.15)

{axis_synome-0.1.0.dev61 → axis_synome-0.1.0.dev63}/tests/axis_synome/asc/test_dab.py

@@ -15,8 +15,9 @@ SPARK = EligiblePrimeAgentASC.SPARK
 
 # dab_required
 def test_dab_required_is_fraction_of_asc():
-    # asc = resting(USDC LitePSM=200) + latent(USDC SparkLend=100) = 300
-    # required = 300 * 0.25 = 75
+    # portfolio = 200 + 100 = 300
+    # min_required_asc = portfolio * 0.05 = 15
+    # dab = min_required_asc * 0.25 = 3.75
     positions = [
         Position(
             asset=Asset(
@@ -45,4 +46,4 @@ def test_dab_required_is_fraction_of_asc():
             value_usd=100.0,
         ),
     ]
-    assert dab_required(SPARK, positions) == pytest.approx(75.0)
+    assert dab_required(SPARK, positions) == pytest.approx(3.75)

{axis_synome-0.1.0.dev61 → axis_synome-0.1.0.dev63}/tests/axis_synome/asc/test_latent_asc.py

@@ -81,11 +81,11 @@ def test_cash_stablecoin_in_morpho_counts():
     positions = [
         Position(
             asset=Asset(
-                token=Token.DAI,
+                token=Token.PYUSD,
                 protocol=Protocol.MORPHO,
                 network=Network.ETHEREUM_MAINNET,
                 address=MOCK_ADDRESS,
-                underlying_asset=Token.DAI,
+                underlying_asset=Token.PYUSD,
                 underlying_asset_address=MOCK_ADDRESS,
                 underlying_asset_source="",
                 categories=MOCK_CATEGORIES,
@@ -169,7 +169,7 @@ def test_pool_with_unknown_pairing_counts_as_latent():
 
 
 def test_non_cash_stablecoin_in_lending_is_excluded():
-    # Only CASH_STABLECOINS (USDC, USDS, DAI, USDT) qualify.
+    # Only CASH_STABLECOINS (USDC, USDT, pyUSD) qualify.
     positions = [
         Position(
             asset=Asset(