axis-synome 0.1.dev184__tar.gz → 0.1.dev185__tar.gz

{axis_synome-0.1.dev184 → axis_synome-0.1.dev185}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: axis-synome
-Version: 0.1.dev184
+Version: 0.1.dev185
 Summary: Axis specification modules (entities, formulas, validators)
 Project-URL: Repository, https://github.com/archon-research/next-gen-atlas
 Project-URL: Documentation, https://github.com/archon-research/next-gen-atlas

{axis_synome-0.1.dev184 → axis_synome-0.1.dev185}/WRITING_SPECS.md

@@ -1,6 +1,6 @@
 # How to Write Axis Specs
 
-This guide distills the principles and conventions used in `specs/src/axis`. It is expected that new specs follow these
+This guide distills the principles and conventions used in `python/axis_synome/src/axis_synome/spec`. It is expected that new specs follow these
 principles as much as possible. The purpose of the principles and conventions is ensure that specs remain parseable, convertible to (SymPy-backed) mathematical expressions, and that they become easy to read and navigate.
 
 This is to facilitate the following goals, paraphrased from the [Axis Synome TechSpec](https://www.notion.so/Axis-Synome-Tech-Spec-30ab87693a5a8024ab3fe29ba5c3421c?source=copy_link):
@@ -17,10 +17,9 @@ This is to facilitate the following goals, paraphrased from the [Axis Synome Tec
 Specs encode Atlas calculation rules directly in typed Python.
 They are declarative, deterministic, side‑effect‑free computations; no I/O or mutable state.
 
-They are organized into the `axis` namespace which contains a submodule/subdirectory `entities/` that defines dataclasses and Enums for domain inputs and constants. Many of these correspond to or stem from Atlas abstractions (typically, A6). In addition there are submodules for different types of risk calculations. These sub-directories should
-generally correspond to risk calculations for specific asset types (applicable to Prime agents), but this is not a fully enforced/enforceable dichotomy. Each of these submodules contains formulas:
+They are organized into the `axis_synome.spec` namespace which contains a submodule/subdirectory `entities/` that defines dataclasses and Enums for domain inputs and constants. Many of these correspond to or stem from Atlas abstractions (typically, A6). In addition there are submodules grouped by calculation concepts (Atlas‑style, e.g., capital composition, credit risk, exposure transformation/mitigation). Asset classes live in `entities/` rather than as top‑level spec organization. This structure is pragmatic and reversible. Each of these submodules contains formulas:
 
-- Formulas are pure functions over entities that specify computations internally.
+- Formulas are pure functions over entities that specify computations.
 - Each set of formulas that corresponds to a specific risk calculation, e.g., for a specific asset class is organized into its own namespace.
 - Functions are kept small; compose into top‑level results.
 - Independently testable and extractor‑friendly.
@@ -47,27 +46,47 @@ Relations are traversable: clients and tooling can evaluate predicates across th
 
 ## Building Blocks
 
-### Metadata
+### Documentation and Provenance
 
-Metadata objects are used to annotate types used.
+- Prefer function docstrings for descriptive text. Put the human‑readable description of what a formula does into the function’s docstring. Docstrings are code‑adjacent, IDE/hover friendly, and can be used to generate documentation.
+- As functions are also math formulas and documentation from docstrs will also be used for the mathematical exposition, avoid Python specific terminology.
+- Avoid duplicating long‑form descriptions in metadata.
+- Put Atlas provenance in docstrings using reST-style fields such as `:source_uuid: ...`.
+- In `python/axis_synome/src/**/formulas/*.py`, public functions are treated as formulas by convention, so plain return types like `-> float` or `-> bool` are preferred.
+- Outside formula modules, docstring fields such as `:source_uuid:` provide explicit opt-in for formula discovery.
+- For constants and parameters, use `Final[...]` and trailing string literal docstrings.
+- Avoid per‑formula READMEs. Prefer generating documentation from docstrings to keep content in sync with code.
 
-Generally, Metadata is used to provide additional information about a parameter (variable), formula (function), an entity type (dataclass), or a concrete entity (an instance of a dataclass or Enum).
+Examples:
 
 ```python
-(
-    Metadata(
-        description="Maximum fraction of ASC that may be Latent",
-        source="Atlas A3.2",
-    ),
-)
-```
+def asc(prime: EligiblePrimeAgentASC, positions: list[Position]) -> float:
+    """
+    Total Actively Stabilizing Capital for a prime.
+
+    Sum of resting and latent ASC for a given prime over its positions.
+
+    :source_uuid: 62495dee-8d2a-45d4-87c4-01150e3db3c8
+    """
+    ...
+
 
-TODO: Describe atlas schema / dir structure usage
+# If no corresponding Atlas section exists, just omit the marker and keep the docstring:
+
+
+def asc(prime: EligiblePrimeAgentASC, positions: list[Position]) -> float:
+    """
+    Total Actively Stabilizing Capital for a prime.
+
+    Sum of resting and latent ASC for a given prime over its positions.
+    """
+    ...
+```
 
 ### Parameters
 
-- Use `Final[Annotated[T, Metadata(...)] ]` for governance‑set constants.
-- Parameter names and metadata (`formula_id`, `description`, `source`) provide machine‑readable identities used in the graph, audits, and codegen.
+- Use `Final[T]` for governance‑set constants.
+- Parameter names plus structured docstring markers like `:source_uuid:` provide machine‑readable identities used in the graph, audits, and codegen. Place human‑readable descriptions in trailing constant docstrings.
 
 ### Units
 
@@ -81,25 +100,38 @@ For instance, a float-compatible `usd` type may be introduced (this is used in s
 
 ### Parameters
 
-- Represent global governance parameters as module‑level, annotated constants.
-- Use `typing.Final` for immutability and `typing.Annotated` carrying `Metadata` for description/Atlas reference.
+- Represent global parameters as module‑level, annotated constants.
+- Use `typing.Final` as the constant marker and place descriptive text and Atlas provenance in the trailing string literal docstring.
 - When parameters vary per entity (e.g., per Prime), model them as fields on the entity dataclass with validation (e.g., `pydantic.dataclasses.dataclass` + `Field`).
+- If a constant has no relevant Atlas section, just omit the `:source_uuid:` marker and provide the human description as the trailing string literal docstring.
 
 Example:
 
 ```python
-from typing import Annotated, Final
-from axis_synome.spec_support.metadata import Metadata
-
-MAX_LATENT_ASC: Final[
-    Annotated[
-        usd,  # usd is a floating point value compatible with Python float
-        Metadata(
-            description="Maximum fraction of ASC that may be Latent",
-            source="Sky Atlas — ASC Cap",
-        ),
-    ]
-] = 0.25
+from typing import Final
+
+MAX_LATENT_ASC: Final[usd] = 0.25  # usd is a floating point value compatible with Python float
+"""Maximum latent ASC fraction.
+
+:source_uuid: 5e300cdb-b221-4b6f-9c4a-11502133a1f9
+"""
+```
+
+Constant descriptions (docstrings)
+
+- For constants, place the human‑readable description as a bare string literal immediately following the assignment. The parser treats this trailing string as the constant’s “docstring” and extracts it into the graph.
+- Keep `source_uuid` and other structured fields in the trailing docstring using markers such as `:source_uuid: ...`.
+
+Example:
+
+```python
+from typing import Final
+
+DAB_REQUIRED_PCT: Final[float] = 0.25
+"""Required DAB as a fraction of total ASC.
+
+:source_uuid: 1e129119-a2ce-4978-b235-c50f2a1c5e2e
+"""
 ```
 
 ---
@@ -137,10 +169,16 @@ class Position:
 Note that all entity fields are typed to a closed set, the set of allowed values are in each case
 a fixed set instiantiated objects. `value_usd` is additionally restricted with an annotation ensuring that only positive values are supplied.
 
+#### Entities Layout (Formula‑Local vs Common)
+
+- Start formula‑local: keep entities within each formula’s package initially (`axis/<formula>/entities/`).
+- Uplift to shared only when needed: introduce shared entities at top level (`axis/entities/`) when the same entities are used by multiple formulas and sharing materially reduces duplication. A pragmatic threshold is when a third, independent formula reuses the same entities.
+- Don’t add empty common folders: only create and populate shared folders when you actually have shared entities.
+- Moving entities is a breaking change: import paths change when uplifting to shared. Provide re‑exports where feasible during transitions and bump the major version when breaking import paths.
 ### Formulas
 
 - Formula functions are pure: `(inputs) -> output`, but process inputs to intermediate values by calling other formula functions (or by utilizing a restricted set of built-in functions and external functions)
-- They can and should be annotated, i.e., the return value is annotated with a `Metadata` object.
+- In formula modules, prefer plain return types and put structured provenance such as `source_uuid` in the docstring. Outside formula modules, docstring fields such as `:source_uuid:` provide explicit opt-in.
 - They accept closed‑world Enums to encode eligibility and preconditions; use union types for overlapping eligible sets when needed.
 - Compose helpers; keep inclusion/exclusion criteria explicit in docstrings.
 
@@ -206,6 +244,7 @@ def asc(prime: EligiblePrimeAgentASC, positions: list[Position]) -> float:
     """
     Total Actively Stabilizing Capital for a prime.
 
+    Computes the sum of resting and latent ASC for a given prime over its positions.
     """
     # Enum values are concrete PrimeAgent instances
     resting_asc_usd: float = resting_asc(positions)
@@ -219,14 +258,8 @@ Each of those assignments induces a formula definition, `formula_id(resting_asc_
 
 Similarly, the return statement induces a formula definition, `formula_id(asc) = formula_id(resting_asc_usd) + formula_id(latent_asc_usd)`.
 
-In the example above, the function just returns a `float`. Whenever possible we should add an
-annotation that associates metadata with the function, i.e.,
-
-```python
-def asc(prime: EligiblePrimeAgentASC, positions: list[Position]) -> Annotated[float, Metadata(...)]:
-  ):
-  ...
-```
+In formula modules, the function can just return a plain scalar type and carry provenance in the
+docstring, e.g. `def asc(...) -> float: ...`.
 
 #### Boolean functions as constraints
 
@@ -236,7 +269,9 @@ Boolean constraint functions that take closed‑world sets (e.g., `EligiblePrime
 Specification functions that take one or more closed-world Entity argument are constraints that should hold true for **all** combinations of the matching inputs to the functions.
 
 ```python
-def compliant_prime(prime: EligiblePrimeAgentASC) -> Annotated[bool, Metadata(...)]: ...
+def compliant_prime(
+    prime: EligiblePrimeAgentASC,
+) -> bool: ...
 ```
 
 Multi-input constraints are evaluated across the Cartesian product of their closed-world domains:
@@ -247,32 +282,43 @@ For instance, we might have a constraint that two distinct primes do not share a
 def portfolio_diversification(
     prime_a: PrimeAgentAll,
     prime_b: PrimeAgentAll,
-) -> Annotated[bool, Metadata("Distinct primes do not concentrate identical assets", "Atlas Ref")]:
-    """Verifies that no two distinct primes hold the same asset above a threshold."""
+) -> bool:
+    """Verifies that no two distinct primes hold the same asset above a threshold.
+
+    :source_uuid: 62495dee-8d2a-45d4-87c4-01150e3db3c8
+    """
     return prime_a == prime_b or not (asset in prime_a.assets and asset in prime_b.assets)
 ```
 
 Assuming that `PrimeAgentAll` is an Enum consisting of prime agent instances, tooling evaluates this constraint across the Cartesian product `PrimeAgentAll × PrimeAgentAll`, ensuring the predicate holds for all combinations where prime_a ≠ prime_b.
 
 
+### Testing
+
+- Happy‑path tests only (internal initially): provide one simple, end‑to‑end test per formula demonstrating basic execution flow. Avoid asserting on highly specific numerical guarantees unless essential; prefer sanity checks that exercise the graph and opaque boundaries.
+- Location: keep tests under `python/axis_synome/tests/` organized by concept/module. Treat these as internal by default; they can be published later based on demand.
+- Declarative first: specs are declarative and amenable to static verification; tests complement by documenting usage and catching regressions in opaque integrations.
+
+#### Reference Implementations for Opaque Functions
+
+- Opaque functions (e.g., ARIMA) are too complex to fully specify as pure math. To execute happy‑path tests, provide a minimal “test math engine” or reference implementation used only by tests.
+- Do not publish as an official runtime dependency initially. If users request a ready‑made engine, consider publishing a separate package later.
+- Multiple valid approaches may exist; tests should pick one concrete implementation as an example without constraining others.
+
+
 ## Starter Template
 
 Start a new spec module with (simplified example; in real modules, entities typically live in their own package folder):
 
 ```python
 # parameters.py
-from typing import Annotated, Final
-from axis_synome.spec_support.metadata import Metadata
-
-THRESHOLD: Final[
-    Annotated[
-        float,
-        Metadata(
-            description="Breach threshold in USD",
-            source="Atlas Ref",
-        ),
-    ]
-] = 1_000_000.0
+from typing import Final
+
+THRESHOLD: Final[float] = 1_000_000.0
+"""Example threshold constant.
+
+:source_uuid: 62495dee-8d2a-45d4-87c4-01150e3db3c8
+"""
 ```
 
 ```python
@@ -300,8 +346,6 @@ class ItemSet(Enum):
 
 ```python
 # formulas.py
-from typing import Annotated
-from axis_synome.spec_support.metadata import Metadata
 from .parameters import THRESHOLD
 from .entities.items import ItemSet, EligibleOwner
 
@@ -326,14 +370,11 @@ def owner_item_value(owner: EligibleOwner, item: ItemSet) -> float:
 
 def total_value(
     owner: EligibleOwner,
-) -> Annotated[
-    float,
-    Metadata(
-        formula_id="formula_total_value",
-        description="Total USD value from closed‑world item set",
-        source="Atlas Ref",
-    ),
-]:
+) -> float:
+    """Total value for an eligible owner.
+
+    :source_uuid: DOC-EXAMPLE-UUID
+    """
     # Computes over the closed‑world ItemSet domain
     return sum(owner_item_value(owner, it) for it in ItemSet)
 
@@ -350,7 +391,7 @@ def threshold_satisfied(owner: EligibleOwner) -> bool:
   - Aggregators: `sum`, `min`, `max`, `any`, `all` over generator expressions.
   - Generator expressions and simple `range(...)` where needed.
   - Selected `math.*` (e.g., `log`, `exp`, `sqrt`, `pow`).
-  - Imports from `axis`, `synome`, `typing`, `dataclasses`, `enum`, `pydantic`, and bare `math`.
+  - Imports from `axis_synome.spec`, `synome`, `typing`, `dataclasses`, `enum`, `pydantic`, and bare `math`.
 
 - Avoid / Disallowed
   - Mutation, I/O, networking, side effects; exceptions and `try/except`.
@@ -398,7 +439,7 @@ The parser extracts formulas from typed Python by walking the function AST and l
   - Dict literals and dict comprehensions are disallowed in formulas. Set comprehensions are not currently supported by the parser; if used, they will not be converted and may fallback to uninterpreted forms.
   - Exceptions and side effects are out of scope by design.
 
-Metadata extraction: the parser recognizes `formula_id`, `description`, and `source` via `Annotated[..., Metadata(...)]` on return types. Units are not required; document units in docstrings if needed.
+Formula extraction: in `python/axis_synome/src/**/formulas/*.py`, the parser treats public functions as formulas by convention and reads `source_uuid` from docstring fields such as `:source_uuid: ...`. Outside formula modules, those docstring fields remain the explicit opt-in. Prefer putting descriptions in docstrings; units are not required and can be documented there as needed.
 
 ---
 
@@ -408,7 +449,7 @@ Use the Makefile targets to run checks consistently:
 
 - Lint (ruff): `make lint` → `uv run ruff check .`
 - Format (ruff): `make format` or `make format-check`
-- Specs lint (flake8 in specs): `make lint-specs` (runs from `specs/`)
+- Specs lint (flake8 in specs): `make lint-specs` (runs from `python/axis_synome/`)
 - Type check (Ty): `make typecheck` (runs `ty check` for `src/` and `explorations/`)
 - All checks: `make check-all`
 
@@ -425,19 +466,19 @@ Use the Makefile targets to run checks consistently:
   - Run: `make lint` for checks, `make fix` to auto-fix, `make format` for formatting.
 
 - Flake8 (spec-subset validator)
-  - In `specs/`, Flake8 runs a custom plugin that emits AXS00x errors when a file uses constructs outside the allowed subset defined in `axis_common.python_subset`.
+  - In `python/axis_synome/`, Flake8 runs a custom plugin that emits AXS00x errors when a file uses constructs outside the allowed subset defined in `axis_synome.spec_validator.python_subset`.
   - Examples of disallowed patterns: nested functions in formulas, methods in dataclasses/Enums, non-whitelisted imports, f-strings, dict/set comprehensions, `try/except`, `yield`, walrus `:=`, unapproved builtins.
   - Only spec files are validated by the plugin; editor integrations surface these as AXS diagnostics.
-  - Run: `make lint-specs` (executes from `specs/`).
+  - Run: `make lint-specs` (executes from `python/axis_synome/`).
 
 - Ty (static type checking)
   - Validates function signatures, dataclass fields, and return types across runtime code and specs. Types must line up; otherwise the graph edges inferred from signatures become unsound.
-  - Encourages narrow, precise types on inputs/outputs (e.g., closed-world Enums, `Final`, `Annotated[..., Metadata(...)]`).
+  - Encourages narrow, precise types on inputs/outputs (e.g., closed-world Enums, `Final`, and precise scalar return types).
   - Run: `make typecheck`.
 
 ### How Checks Align With The Parser
 
-- Single source of truth for the subset. The same allowlist powering the Flake8 plugin (`axis_common.python_subset`) is used by the parser when walking function ASTs to produce SymPy. If Flake8 passes, the parser will not encounter unexpected statement/expression kinds.
+- Single source of truth for the subset. The same allowlist powering the Flake8 plugin (`axis_synome.spec_validator.python_subset`) is used by the parser when walking function ASTs to produce SymPy. If Flake8 passes, the parser will not encounter unexpected statement/expression kinds.
 - Safe constructs are lowered deterministically. Comprehensions, boolean ops, comparisons, `sum/min/max`, selected `math.*`, and simple conditionals become SymPy expressions or uninterpreted functions with clear bounds.
 - Disallowed constructs block extraction early. If you see an `AXS001 ... is not allowed` error, change the code to an allowed equivalent (e.g., use a generator expression and `sum(...)` instead of a loop; prefer ternary `x if c else y` over complex branching inside expressions).
 
@@ -445,14 +486,14 @@ Use the Makefile targets to run checks consistently:
 
 - Signatures define edges. A formula like `def asc(prime: EligiblePrimeAgentASC, positions: list[Position]) -> float` induces edges from each `EligiblePrimeAgentASC` member to `asc`, and from any sub-formulas it calls to `asc`.
 - Closed-world Enums enable universal and product quantification. Boolean constraints over Enums are checked over all members or Cartesian products without execution, thanks to types.
-- Entities and parameters carry semantics. Dataclass fields typed to domain-specific classes and parameters typed as `Final[Annotated[T, Metadata(...)] ]` provide machine-readable identities (`formula_id`, `description`, `source`) used in graph labeling, audits, and downstream codegen.
+- Entities and parameters carry semantics. Dataclass fields typed to domain-specific classes and typed constants such as `Final[T]` provide machine-readable identities; `source_uuid` comes from docstring markers such as `:source_uuid:` and is used in graph labeling, audits, and downstream codegen. Place long‑form descriptions in docstrings.
 - Type checking safeguards graph integrity. If you widen a type (e.g., `Any` or a loose `str`) you reduce the graph’s precision; Ty will highlight mismatches so specs remain traversable and analyzable.
 
 ### Typical Violations And Fixes
 
 - For-loops inside formulas → Replace with generator expressions plus `sum(...)`, `any(...)`, or `all(...)`.
 - Dict/set comprehensions → Move structure-building to entities or use lists/tuples; keep formula bodies expression-centric.
-- Unapproved builtins/imports → Use only builtins in the allowlist and imports under permitted prefixes (`axis`, `typing`, `dataclasses`, `enum`, `pydantic`, `synome`, or `math`).
+- Unapproved builtins/imports → Use only builtins in the allowlist and imports under permitted prefixes (`axis_synome.spec`, `typing`, `dataclasses`, `enum`, `pydantic`, `synome`, or `math`).
 - Methods in dataclasses/Enums → Move logic into free functions; limit classes to annotated fields (dataclasses) or constant members (Enums).
 - Missing/loose types → Add precise argument and return annotations; prefer closed-world Enums where policy implies eligibility.
 
@@ -483,12 +524,11 @@ These hypothetical examples show how mathematical expression/equations can be co
 $\mathrm{PortfolioUSD} = H_{\mathrm{USDC}} + H_{\mathrm{USDT}} + H_{\mathrm{USDS}} +  H_{\mathrm{DAI}}$
 
 ```python
-def portfolio_usd(
-    h_usdc: float, h_usdt: float, h_usds: float, h_dai: float
-) -> Annotated[
-    float,
-    Metadata(description="Total USD across stablecoin holdings", source="Example"),
-]:
+def portfolio_usd(h_usdc: float, h_usdt: float, h_usds: float, h_dai: float) -> float:
+    """Total USD across stablecoin holdings.
+
+    :source_uuid: DOC-EXAMPLE-UUID
+    """
     holdings = [("USDC", h_usdc), ("USDT", h_usdt), ("USDS", h_usds), ("DAI", h_dai)]
     total: float = sum(value for _, value in holdings)
     return total
@@ -501,23 +541,21 @@ $\mathrm{margin} = \dfrac{\mathrm{assetsUSD}}{\mathrm{debtUSD}} - \mathrm{minRat
 $\mathrm{collateral\_ratio\_satisfied} \iff \mathrm{margin} \ge 0$
 
 ```python
-def collateral_ratio_margin(
-    assets_usd: float, debt_usd: float, min_ratio: float
-) -> Annotated[
-    float,
-    Metadata(description="Collateral ratio minus minimum", source="Example"),
-]:
+def collateral_ratio_margin(assets_usd: float, debt_usd: float, min_ratio: float) -> float:
+    """Collateral ratio minus minimum.
+
+    :source_uuid: DOC-EXAMPLE-UUID
+    """
     ratio: float = assets_usd / debt_usd
     margin: float = ratio - min_ratio
     return margin
 
 
-def collateral_ratio_satisfied(
-    assets_usd: float, debt_usd: float, min_ratio: float
-) -> Annotated[
-    bool,
-    Metadata(description="Collateral ratio >= minimum", source="Example"),
-]:
+def collateral_ratio_satisfied(assets_usd: float, debt_usd: float, min_ratio: float) -> bool:
+    """True when collateral ratio meets or exceeds the minimum.
+
+    :source_uuid: DOC-EXAMPLE-UUID
+    """
     return collateral_ratio_margin(assets_usd, debt_usd, min_ratio) >= 0.0
 ```
 
@@ -531,10 +569,11 @@ $\mathrm{haircut}(\sigma_{30\mathrm{d}}) = \begin{cases}
 ```python
 def volatility_haircut(
     vol_30d: float,
-) -> Annotated[
-    float,
-    Metadata(description="Haircut by 30d volatility threshold", source="Example"),
-]:
+) -> float:
+    """Haircut by 30d volatility threshold.
+
+    :source_uuid: DOC-EXAMPLE-UUID
+    """
     return 0.02 if vol_30d < 0.2 else 0.05
 ```
 
@@ -547,10 +586,11 @@ $w_{\mathrm{PSM}}=U_{\mathrm{PSM}}/T,\quad w_{\mathrm{Curve}}=U_{\mathrm{Curve}}
 $\max\{w_{\mathrm{PSM}}, w_{\mathrm{Curve}}, w_{\mathrm{Uni}}\} \le \mathrm{cap}$
 
 ```python
-def max_venue_concentration(psm_usd: float, curve_usd: float, uni_usd: float, cap: float) -> Annotated[
-    bool,
-    Metadata(description="Max venue share <= cap", source="Example"),
-]:
+def max_venue_concentration(psm_usd: float, curve_usd: float, uni_usd: float, cap: float) -> bool:
+    """True when the maximum venue share is at or below the cap.
+
+    :source_uuid: DOC-EXAMPLE-UUID
+    """
     total: float = psm_usd + curve_usd + uni_usd
     w_psm: float = psm_usd / total
     w_curve: float = curve_usd / total
@@ -564,9 +604,9 @@ def max_venue_concentration(psm_usd: float, curve_usd: float, uni_usd: float, ca
   - Use types (dataclasses, Enums, precise signatures) to encode policy and traversable relations.
 
 - Minimal template
-  - Parameters: `Final[Annotated[T, Metadata(...)] ]` for governance‑set constants.
+  - Parameters: `Final[T]` for governance‑set constants, with provenance in trailing docstrings.
   - Entities: frozen dataclasses and closed‑world Enums of concrete instances.
-  - Formulas: pure functions over these types with precise return annotations (prefer `Annotated[..., Metadata(...)]`).
+  - Formulas: pure functions over these types with precise return types; put provenance in docstrings.
 
 - Do / Don’t (subset cheat‑sheet)
   - Do: use generator expressions + `sum/min/max/any/all`, ternary `x if c else y`, selected `math.*`, and composition of small helpers.
@@ -584,12 +624,11 @@ def max_venue_concentration(psm_usd: float, curve_usd: float, uni_usd: float, ca
 $\mathrm{PV} = \sum_{i=0}^{n-1} \dfrac{\mathrm{CF}_i}{(1+r)^{i+1}}$
 
 ```python
-def present_value(
-    cashflows: list[float], r: float
-) -> Annotated[
-    float,
-    Metadata(description="Sum CF[i]/(1+r)^(i+1) over i in [0,n)", source="Example"),
-]:
+def present_value(cashflows: list[float], r: float) -> float:
+    """Present value of discounted cash flows.
+
+    :source_uuid: DOC-EXAMPLE-UUID
+    """
     n: int = len(cashflows)
     return sum(cashflows[i] / (1.0 + r) ** (i + 1) for i in range(n))
 ```
@@ -599,12 +638,11 @@ def present_value(
 $\forall i \in \{0,\dots,n-1\}:\; p_i \ge \tau$
 
 ```python
-def all_positions_above(
-    positions: list[float], threshold: float
-) -> Annotated[
-    bool,
-    Metadata(description="All positions >= threshold", source="Example"),
-]:
+def all_positions_above(positions: list[float], threshold: float) -> bool:
+    """All positions above a threshold.
+
+    :source_uuid: DOC-EXAMPLE-UUID
+    """
     return all(p >= threshold for p in positions)
 ```
 
@@ -632,3 +670,14 @@ Use only when the operation cannot be expressed in the allowed, parser‑friendl
   - Keep wrappers zero‑logic (no exceptions/branching); just delegate to `get_engine()`.
   - Use precise, stable types and consistent snake_case names.
   - Briefly document new opaque functions in `opaque/README.md` (purpose, signature, runtime notes).
+
+## Atlas Integration
+
+- Keep Atlas UUIDs in docstrings using `:source_uuid: ...` when available. If no Atlas section applies, omit the marker entirely.
+- Prefer docstrings in specs as the authoritative descriptive source. Atlas Markdown pages can be “hollowed out” to minimal anchors that link back to Synome specs and reuse docstrings when possible. This approach avoids duplicate, drifting descriptions. Pending Atlas Access team alignment.
+
+## Versioning and Backwards Compatibility
+
+- Early phase: limited backwards‑compatibility promises. We may iterate quickly across major versions.
+- Breaking changes (e.g., moving entities from formula‑local to shared `axis/entities/`, changing import paths) require a major version bump.
+- Where feasible, provide temporary re‑exports/shims to ease upgrades, but prefer clarity over long‑term indirection.

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

{axis_synome-0.1.dev184 → axis_synome-0.1.dev185}/src/axis_synome/spec/asc/formulas/asc.py

@@ -1,31 +1,14 @@
-from typing import Annotated
-
 from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
 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
-from axis_synome.spec_support.metadata import Metadata
-
-BLAH = 5
-
-
-"""Seconds to wait before the connection times out."""
-
-"hello"
 
 
-def asc(
-    prime: EligiblePrimeAgentASC, positions: list[Position]
-) -> Annotated[
-    float,
-    Metadata(
-        description="Total Actively Stabilizing Capital for a prime: resting ASC plus latent ASC.",
-        source_uuid="62495dee-8d2a-45d4-87c4-01150e3db3c8",
-    ),
-]:
+def asc(prime: EligiblePrimeAgentASC, positions: list[Position]) -> float:
     """
     Total Actively Stabilizing Capital for a prime.
 
+    :source_uuid: 62495dee-8d2a-45d4-87c4-01150e3db3c8
     """
     resting_asc_usd: float = resting_asc(positions)
     latent_asc_usd: float = latent_asc(prime, positions)

axis_synome-0.1.dev185/src/axis_synome/spec/asc/formulas/asc_collateral_ratio.py

@@ -0,0 +1,36 @@
+from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
+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
+
+
+def collateral_portfolio(
+    positions: list[Position],
+) -> float:
+    """Total Collateral Portfolio value for a prime: sum of all positions.
+
+    :source_uuid: 64e1390f-68a1-43ec-87a8-8ae7b990f7ec
+    """
+    return sum(p.value_usd for p in positions)
+
+
+def asc_collateral_ratio(prime: EligiblePrimeAgentASC, positions: list[Position]) -> float:
+    """ASC collateral ratio slack.
+
+    Returns the arithmetic result unconditionally.  A negative value means
+    ASC is below the required minimum fraction of the Collateral Portfolio.
+
+    :source_uuid: 475fe222-9e4a-4e9d-9be6-a7a424ce02f8
+    """
+    agent = prime.value
+    asc_usd: float = resting_asc(positions) + latent_asc(prime, positions)
+    portfolio_usd: float = collateral_portfolio(positions)
+    return asc_usd - portfolio_usd * agent.min_pct_asc_of_collateral
+
+
+def asc_collateral_ratio_satisfied(prime: EligiblePrimeAgentASC, positions: list[Position]) -> bool:
+    """Boolean ASC collateral ratio compliance predicate. True iff asc_collateral_ratio >= 0.
+
+    :source_uuid: 475fe222-9e4a-4e9d-9be6-a7a424ce02f8
+    """
+    return asc_collateral_ratio(prime, positions) >= 0.0

{axis_synome-0.1.dev184 → axis_synome-0.1.dev185}/src/axis_synome/spec/asc/formulas/asc_incentive.py

@@ -1,10 +1,7 @@
-from typing import Annotated
-
 from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
 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
-from axis_synome.spec_support.metadata import Metadata
 
 # base_float and treasury_bill_rate are both expressed as params.
 
@@ -14,15 +11,10 @@ def asc_incentive(
     positions: list[Position],
     base_rate: float,
     treasury_bill_rate: float,
-) -> Annotated[
-    float,
-    Metadata(
-        description="ASC incentive payment: eligible ASC multiplied by the spread between base rate and treasury bill rate.",
-        source_uuid="693330d6-9072-4054-bd61-d788537e34e8",
-    ),
-]:
-    """
-    ASC incentive payment
+) -> float:
+    """ASC incentive payment: eligible ASC times (base_rate - treasury_bill_rate).
+
+    :source_uuid: 693330d6-9072-4054-bd61-d788537e34e8
     """
     eligible_asc_usd: float = resting_asc(positions) + latent_asc(prime, positions)
     return eligible_asc_usd * (base_rate - treasury_bill_rate)

axis_synome-0.1.dev185/src/axis_synome/spec/asc/formulas/dab.py

@@ -0,0 +1,24 @@
+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.latent_asc import latent_asc
+from axis_synome.spec.asc.formulas.resting_asc import resting_asc
+
+DAB_REQUIRED_PCT: Final[float] = 0.25
+"""Required DAB as a fraction of total ASC.
+
+:source_uuid: 1e129119-a2ce-4978-b235-c50f2a1c5e2e
+"""
+
+
+def dab_required(
+    prime: EligiblePrimeAgentASC,
+    positions: list[Position],
+) -> float:
+    """Required DAB: DAB_REQUIRED_PCT of ASC.
+
+    :source_uuid: 1e129119-a2ce-4978-b235-c50f2a1c5e2e
+    """
+    asc_usd = resting_asc(positions) + latent_asc(prime, positions)
+    return asc_usd * DAB_REQUIRED_PCT

{axis_synome-0.1.dev184 → axis_synome-0.1.dev185}/src/axis_synome/spec/asc/formulas/latent_asc.py

@@ -1,21 +1,10 @@
-from typing import Annotated
-
 from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
 from axis_synome.spec.asc.entities.protocol_sets import LENDING_PROTOCOLS, POOL_PROTOCOLS
 from axis_synome.spec.asc.entities.tokens import CASH_STABLECOINS
 from axis_synome.spec.asc.entities.types import Position
-from axis_synome.spec_support.metadata import Metadata
 
 
-def latent_asc(
-    prime: EligiblePrimeAgentASC, positions: list[Position]
-) -> Annotated[
-    float,
-    Metadata(
-        description="Latent ASC: stabilizing capital not immediately liquid, held by a prime.",
-        source_uuid="35ce6b38-9fc1-456e-93da-10ab1468a8bf",
-    ),
-]:
+def latent_asc(prime: EligiblePrimeAgentASC, positions: list[Position]) -> float:
     """Latent ASC for a prime: which is the stabilizing capital not immediately liquid.
 
     Includes:
@@ -25,6 +14,8 @@ def latent_asc(
 
     Pool positions paired with USDS are excluded (those contribute to
     RestingASC).
+
+    :source_uuid: 35ce6b38-9fc1-456e-93da-10ab1468a8bf
     """
     agent = prime.value
     return sum(

{axis_synome-0.1.dev184 → axis_synome-0.1.dev185}/src/axis_synome/spec/asc/formulas/ratio_latent_asc.py

@@ -1,25 +1,16 @@
-from typing import Annotated
-
 from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
 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
-from axis_synome.spec_support.metadata import Metadata
 
 
-def ratio_latent_asc(
-    prime: EligiblePrimeAgentASC, positions: list[Position]
-) -> Annotated[
-    float,
-    Metadata(
-        description="Latent ASC ratio slack: permitted latent cap minus actual latent ASC. Must be >= 0 for compliance.",
-        source_uuid="5e300cdb-b221-4b6f-9c4a-11502133a1f9",
-    ),
-]:
+def ratio_latent_asc(prime: EligiblePrimeAgentASC, positions: list[Position]) -> float:
     """Latent ASC ratio slack.
 
     Returns the arithmetic result unconditionally.  A negative value means
     LatentASC exceeds the permitted fraction of total ASC.
+
+    :source_uuid: 5e300cdb-b221-4b6f-9c4a-11502133a1f9
     """
     agent = prime.value
     latent_usd: float = latent_asc(prime, positions)
@@ -27,14 +18,9 @@ def ratio_latent_asc(
     return total_usd * agent.max_pct_latent_asc - latent_usd
 
 
-def latent_asc_ratio_satisfied(
-    prime: EligiblePrimeAgentASC, positions: list[Position]
-) -> Annotated[
-    bool,
-    Metadata(
-        description="True when latent ASC is within the permitted fraction of total ASC.",
-        source_uuid="5e300cdb-b221-4b6f-9c4a-11502133a1f9",
-    ),
-]:
-    """Boolean latent ASC ratio compliance predicate. True iff ratio_latent_asc >= 0."""
+def latent_asc_ratio_satisfied(prime: EligiblePrimeAgentASC, positions: list[Position]) -> bool:
+    """Boolean latent ASC ratio compliance predicate. True iff ratio_latent_asc >= 0.
+
+    :source_uuid: 5e300cdb-b221-4b6f-9c4a-11502133a1f9
+    """
     return ratio_latent_asc(prime, positions) >= 0.0

{axis_synome-0.1.dev184 → axis_synome-0.1.dev185}/src/axis_synome/spec/asc/formulas/resting_asc.py

@@ -1,5 +1,3 @@
-from typing import Annotated
-
 from axis_synome.spec.asc.entities.networks import L2_NETWORKS
 from axis_synome.spec.asc.entities.protocol_sets import (
     GUNI_PROTOCOLS,
@@ -10,18 +8,11 @@ from axis_synome.spec.asc.entities.protocol_sets import (
 )
 from axis_synome.spec.asc.entities.tokens import CASH_STABLECOINS, Token
 from axis_synome.spec.asc.entities.types import Position
-from axis_synome.spec_support.metadata import Metadata
 
 
 def resting_asc(
     positions: list[Position],
-) -> Annotated[
-    float,
-    Metadata(
-        description="Resting ASC: immediately liquid stabilizing capital held by a prime.",
-        source_uuid="4e8cd2d1-4c74-49fd-b3fe-f8b6ccc1a79f",
-    ),
-]:
+) -> float:
     """Resting ASC for a prime: immediately liquid stabilizing capital.
 
     Includes:
@@ -31,6 +22,8 @@ def resting_asc(
     - USDC in G-UNI at eligible fee tiers (0.01% = 0.0001, 0.05% = 0.0005)
 
     All positions are assumed to belong to this prime.
+
+    :source_uuid: 4e8cd2d1-4c74-49fd-b3fe-f8b6ccc1a79f
     """
     return sum(
         p.value_usd

{axis_synome-0.1.dev184 → axis_synome-0.1.dev185}/src/axis_synome/spec/crypto_lending/formulas/lif.py

@@ -7,33 +7,18 @@ following the Morpho protocol specification.
 Reference: https://docs.morpho.org/learn/concepts/liquidation/
 """
 
-from typing import Annotated
+from typing import Final
 
-from axis_synome.spec_support.metadata import Metadata
+BETA: Final[float] = 0.3
+"""Weight parameter for the LLTV in the LIF denominator calculation."""
 
-BETA: Annotated[
-    float,
-    Metadata(
-        description="Morpho liquidation curve steepness parameter",
-    ),
-] = 0.3
-
-M: Annotated[
-    float,
-    Metadata(
-        description="Maximum liquidation incentive factor",
-    ),
-] = 1.15
+M: Final[float] = 1.15
+"""Maximum liquidation incentive factor cap."""
 
 
 def lif(
     lltv: float,
-) -> Annotated[
-    float,
-    Metadata(
-        description="Liquidation incentive factor for a given LLTV",
-    ),
-]:
+) -> float:
     """
     Calculate the liquidation incentive factor (LIF) for a given LLTV.
 

{axis_synome-0.1.dev184 → axis_synome-0.1.dev185}/src/axis_synome/spec/risk_capital/formulas/required_risk_capital.py

@@ -7,22 +7,12 @@ occurs at a given slippage, following the Atlas specification.
 Reference: A.3.2.2.1.1.1.1.1.2 — Calculate Loss Given Default
 """
 
-from typing import Annotated
-
-from axis_synome.spec_support.metadata import Metadata
-
 
 def loss_given_default(
     liquidation_penalty: float,
     slippage: float,
     liquidation_threshold: float,
-) -> Annotated[
-    float,
-    Metadata(
-        description="Fractional loss on a collateral position at a given slippage",
-        source_uuid="c9bd4928-d054-4e89-9a98-720c439b0db3",
-    ),
-]:
+) -> float:
     """
     Calculate the loss given default for a collateral position.
 
@@ -34,6 +24,8 @@ def loss_given_default(
         liquidation_threshold: LT, debt as fraction of collateral at liquidation [0, 1]
 
     Returns a value in [0, 1]. Zero means no loss; 1 means total loss.
+
+    :source_uuid: c9bd4928-d054-4e89-9a98-720c439b0db3
     """
     recovery: float = (1.0 - liquidation_penalty) * (1.0 - slippage) / liquidation_threshold
     return max(0.0, min(1.0, 1.0 - recovery))

{axis_synome-0.1.dev184 → axis_synome-0.1.dev185}/src/axis_synome/spec_validator/checker.py

@@ -49,6 +49,8 @@ class SpecChecker(ast.NodeVisitor):
     # ------------------------------------------------------------------
 
     def visit_Module(self, node: ast.Module) -> None:
+        # Validate trailing string literal constant docstrings where present.
+        self._validate_constant_docstrings(node)
         # Pre-scan for imported names for shadowing detection
         for stmt in node.body:
             if isinstance(stmt, (ast.Import, ast.ImportFrom)):
@@ -68,6 +70,35 @@ class SpecChecker(ast.NodeVisitor):
             else:
                 self.visit(stmt)
 
+    def _validate_constant_docstrings(self, node: ast.Module) -> None:
+        """Validate trailing string literal docstrings for documented constants."""
+        body = list(getattr(node, "body", []))
+        for i, stmt in enumerate(body):
+            target: ast.Name | None = None
+            if isinstance(stmt, ast.AnnAssign) and isinstance(stmt.target, ast.Name):
+                target = stmt.target
+            elif (
+                isinstance(stmt, ast.Assign)
+                and len(stmt.targets) == 1
+                and isinstance(stmt.targets[0], ast.Name)
+            ):
+                target = stmt.targets[0]
+
+            if target is None or not target.id.isupper():
+                continue
+
+            if i + 1 < len(body):
+                nxt = body[i + 1]
+                if isinstance(nxt, ast.Expr) and isinstance(
+                    getattr(nxt, "value", None), ast.Constant
+                ):
+                    val = nxt.value
+                    if isinstance(getattr(val, "value", None), str) and not str(val.value).strip():
+                        self._error(
+                            stmt,
+                            f"Constant '{target.id}' trailing string literal docstring must not be empty",
+                        )
+
     # ------------------------------------------------------------------
     # Function definitions
     # ------------------------------------------------------------------

axis_synome-0.1.dev184/src/axis_synome/spec/asc/formulas/asc_collateral_ratio.py

@@ -1,53 +0,0 @@
-from typing import Annotated
-
-from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
-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
-from axis_synome.spec_support.metadata import Metadata
-
-
-def collateral_portfolio(
-    positions: list[Position],
-) -> Annotated[
-    float,
-    Metadata(
-        description="Total Collateral Portfolio value for a prime: sum of all position values.",
-        source_uuid="64e1390f-68a1-43ec-87a8-8ae7b990f7ec",
-    ),
-]:
-    """Total Collateral Portfolio value for a prime: sum of all positions."""
-    return sum(p.value_usd for p in positions)
-
-
-def asc_collateral_ratio(
-    prime: EligiblePrimeAgentASC, positions: list[Position]
-) -> Annotated[
-    float,
-    Metadata(
-        description="ASC collateral ratio slack: ASC minus the required minimum fraction of the Collateral Portfolio. Must be >= 0 for compliance.",
-        source_uuid="475fe222-9e4a-4e9d-9be6-a7a424ce02f8",
-    ),
-]:
-    """ASC collateral ratio slack.
-
-    Returns the arithmetic result unconditionally.  A negative value means
-    ASC is below the required minimum fraction of the Collateral Portfolio.
-    """
-    agent = prime.value
-    asc_usd: float = resting_asc(positions) + latent_asc(prime, positions)
-    portfolio_usd: float = collateral_portfolio(positions)
-    return asc_usd - portfolio_usd * agent.min_pct_asc_of_collateral
-
-
-def asc_collateral_ratio_satisfied(
-    prime: EligiblePrimeAgentASC, positions: list[Position]
-) -> Annotated[
-    bool,
-    Metadata(
-        description="True when ASC meets or exceeds the required minimum fraction of the Collateral Portfolio.",
-        source_uuid="475fe222-9e4a-4e9d-9be6-a7a424ce02f8",
-    ),
-]:
-    """Boolean ASC collateral ratio compliance predicate. True iff asc_collateral_ratio >= 0."""
-    return asc_collateral_ratio(prime, positions) >= 0.0

axis_synome-0.1.dev184/src/axis_synome/spec/asc/formulas/dab.py

@@ -1,30 +0,0 @@
-from typing import Annotated
-
-from axis_synome.spec.asc.entities.primes import EligiblePrimeAgentASC
-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
-from axis_synome.spec_support.metadata import Metadata
-
-DAB_REQUIRED_PCT: Annotated[
-    float,
-    Metadata(
-        description="Required DAB as a fraction of total ASC.",
-        source_uuid="1e129119-a2ce-4978-b235-c50f2a1c5e2e",
-    ),
-] = 0.25
-
-
-def dab_required(
-    prime: EligiblePrimeAgentASC,
-    positions: list[Position],
-) -> Annotated[
-    float,
-    Metadata(
-        description="Required DAB: DAB_REQUIRED_PCT of total ASC.",
-        source_uuid="1e129119-a2ce-4978-b235-c50f2a1c5e2e",
-    ),
-]:
-    """Required DAB: DAB_REQUIRED_PCT of ASC."""
-    asc_usd = resting_asc(positions) + latent_asc(prime, positions)
-    return asc_usd * DAB_REQUIRED_PCT