axis-synome 0.1.0.dev33__tar.gz → 0.1.0.dev35__tar.gz

{axis_synome-0.1.0.dev33 → axis_synome-0.1.0.dev35}/PKG-INFO

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

{axis_synome-0.1.0.dev33 → axis_synome-0.1.0.dev35}/WRITING_SPECS.md

@@ -14,6 +14,9 @@ This is to facilitate the following goals, paraphrased from the [Axis Synome Tec
 
 ## Core Principles
 
+> If you change this section, also update the distilled review bullets in
+> `.github/instructions/axis-synome.instructions.md`.
+
 Specs encode Atlas calculation rules directly in typed Python.
 They are declarative, deterministic, side‑effect‑free computations; no I/O or mutable state.
 
@@ -48,6 +51,9 @@ Relations are traversable: clients and tooling can evaluate predicates across th
 
 ### Documentation and Provenance
 
+> If you change this section, also update the distilled review bullets in
+> `.github/instructions/axis-synome.instructions.md`.
+
 - 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.

{axis_synome-0.1.0.dev33 → axis_synome-0.1.0.dev35}/pyproject.toml

@@ -74,3 +74,8 @@ select = [
     "PGH004",
 ]
 ignore = ["E402", "E501"]
+
+# Prefer inline suppressions over a [tool.ruff.lint.per-file-ignores] table:
+# put `# ruff: noqa: <CODE>` (file-level) or `# noqa: <CODE>` (line-level) in
+# the source file itself, with a short reason. Keeps the rationale next to the
+# code it justifies and avoids a central table that drifts as files move.

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

axis_synome-0.1.0.dev35/src/axis_synome/spec/asc/entities/alm_proxies.py

@@ -0,0 +1,209 @@
+"""ALM Proxy contract deployments per (Prime, Network).
+
+The ALM Proxy is the contract authorised to allocate liquidity for a Sky Star
+(Prime) on a given chain. Each deployment is defined as a ``Final`` constant
+carrying its Atlas provenance via a ``:source_uuid:`` docstring marker; the
+``AlmProxy`` enum at the bottom of the module aggregates the constants into
+a closed-world set for graph traversal.
+
+The set below is the union of (a) entries currently approved in the Sky
+Atlas — each constant's ``:source_uuid:`` is the authoritative reference to
+the Atlas document — and (b) entries used by downstream consumers that
+maintain their own hard-coded allocation tracker config. Where the two
+disagree the divergence is documented in the constant's docstring. The
+Atlas is the governance source of truth; entries that exist only on the
+consumer side are kept so that axis_synome remains a superset that those
+consumers can pull from.
+"""
+
+from enum import Enum
+from typing import Final
+
+from axis_synome.spec.asc.entities.networks import Network
+from axis_synome.spec.asc.entities.primes import PrimeAgent
+from axis_synome.spec_support.evm_address import EvmAddress
+from axis_synome.spec_support.validated_dataclass import validated_dataclass
+
+
+@validated_dataclass
+class AlmProxyDeployment:
+    """A Sky Star's ALM Proxy contract deployment on a specific network."""
+
+    prime: PrimeAgent
+    network: Network
+    address: EvmAddress
+
+
+# --- Spark (Atlas ALM Contracts parent :source_uuid: 7db865de-8519-464b-8752-f39ecaf54fd2) ---
+
+SPARK_ETHEREUM_MAINNET_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.SPARK,
+    network=Network.ETHEREUM_MAINNET,
+    address=EvmAddress("0x1601843c5E9bC251A3272907010AFa41Fa18347E"),
+)
+"""ALM Proxy contract deployment for Spark on Ethereum Mainnet.
+
+:source_uuid: a29a6751-4809-446c-a659-0dd93ca40379
+"""
+
+
+SPARK_BASE_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.SPARK,
+    network=Network.BASE,
+    address=EvmAddress("0x2917956eFF0B5eaF030abDB4EF4296DF775009cA"),
+)
+"""ALM Proxy contract deployment for Spark on Base.
+
+:source_uuid: 425339ce-8e44-430b-ab8c-6c69f0b757e9
+"""
+
+
+SPARK_ARBITRUM_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.SPARK,
+    network=Network.ARBITRUM,
+    address=EvmAddress("0x92afd6F2385a90e44da3a8B60fe36f6cBe1D8709"),
+)
+"""ALM Proxy contract deployment for Spark on Arbitrum.
+
+:source_uuid: c671b407-fcb2-48eb-8217-2ec156b581ad
+"""
+
+
+SPARK_UNICHAIN_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.SPARK,
+    network=Network.UNICHAIN,
+    address=EvmAddress("0x345E368fcCd62266B3f5F37C9a131FD1c39f5869"),
+)
+"""ALM Proxy contract deployment for Spark on Unichain.
+
+:source_uuid: 6affe08d-0c1c-4cbf-a100-4a04c58220bb
+"""
+
+
+SPARK_OPTIMISM_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.SPARK,
+    network=Network.OPTIMISM,
+    address=EvmAddress("0x876664f0c9Ff24D1aa355Ce9f1680AE1A5bf36fB"),
+)
+"""ALM Proxy contract deployment for Spark on Optimism.
+
+:source_uuid: f1895dfc-a18c-4009-bfd3-1c16c9a62092
+"""
+
+
+SPARK_AVALANCHE_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.SPARK,
+    network=Network.AVALANCHE,
+    address=EvmAddress("0xecE6B0E8a54c2f44e066fBb9234e7157B15b7FeC"),
+)
+"""ALM Proxy contract deployment for Spark on Avalanche.
+
+Discrepancy: the Atlas document below records the address as ``TBD`` while
+sentinel stl-verify config.go already uses the address encoded above. The
+``:source_uuid:`` still points at the Atlas document so the entry remains
+auditable once the Atlas value is filled in.
+
+:source_uuid: 179f186a-079b-4663-b06c-b21f9dec85ca
+"""
+
+
+# --- Grove (Atlas ALM Contracts parent :source_uuid: f233a46b-8dff-4335-8ccf-dc3f1c18a96f) ---
+
+GROVE_ETHEREUM_MAINNET_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.GROVE,
+    network=Network.ETHEREUM_MAINNET,
+    address=EvmAddress("0x491EDFB0B8b608044e227225C715981a30F3A44E"),
+)
+"""ALM Proxy contract deployment for Grove on Ethereum Mainnet.
+
+:source_uuid: fda13ac2-b3ed-4b2a-9be6-9247632dafe3
+"""
+
+
+GROVE_AVALANCHE_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.GROVE,
+    network=Network.AVALANCHE,
+    address=EvmAddress("0x7107DD8F56642327945294a18A4280C78e153644"),
+)
+"""ALM Proxy contract deployment for Grove on Avalanche.
+
+:source_uuid: 0704f4b5-ee5c-455c-932f-94591b8a6594
+"""
+
+
+GROVE_BASE_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.GROVE,
+    network=Network.BASE,
+    address=EvmAddress("0x9B746dBC5269e1DF6e4193Bcb441C0FbBF1CeCEe"),
+)
+"""ALM Proxy contract deployment for Grove on Base.
+
+Discrepancy: sentinel stl-verify config.go does not currently include this
+deployment; the address below is sourced from the Atlas document referenced
+by ``:source_uuid:`` and should be added to the Go side.
+
+:source_uuid: 5c382a94-ce36-4ffa-862b-4718382450fe
+"""
+
+
+GROVE_PLASMA_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.GROVE,
+    network=Network.PLASMA,
+    address=EvmAddress("0x0C462Fff7Cc975bC9F2B0aEB8270febA5FD71e1B"),
+)
+"""ALM Proxy contract deployment for Grove on Plasma.
+
+Discrepancy: sentinel stl-verify config.go does not currently include this
+deployment; the address below is sourced from the Atlas document referenced
+by ``:source_uuid:`` and should be added to the Go side.
+
+:source_uuid: 9d0bcc23-02d4-4389-9c85-707acf900dee
+"""
+
+
+GROVE_PLUME_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.GROVE,
+    network=Network.PLUME,
+    address=EvmAddress("0x1DB91ad50446a671e2231f77e00948E68876F812"),
+)
+"""ALM Proxy contract deployment for Grove on Plume.
+
+:source_uuid: dcf0beac-b93e-41a7-b8b6-98c1d4cc819b
+"""
+
+
+GROVE_MONAD_ALM_PROXY: Final[AlmProxyDeployment] = AlmProxyDeployment(
+    prime=PrimeAgent.GROVE,
+    network=Network.MONAD,
+    address=EvmAddress("0x94B398ACb2fcE988871218221EA6a4a2b26CcCbC"),
+)
+"""ALM Proxy contract deployment for Grove on Monad.
+
+Discrepancy: no Atlas ALM Proxy Contract document exists for Grove on Monad
+yet, so ``:source_uuid:`` is omitted. The address is sourced from sentinel
+stl-verify config.go and should be backfilled in the Atlas.
+"""
+
+
+class AlmProxy(Enum):
+    """Closed-world set of all known ALM Proxy deployments.
+
+    Each member's value is one of the ``Final[AlmProxyDeployment]`` constants
+    defined above. The constants carry the canonical ``:source_uuid:`` markers
+    used by the synome formula extractor; this enum exists so that downstream
+    consumers can traverse the deployments as a closed set.
+    """
+
+    SPARK_ETHEREUM_MAINNET = SPARK_ETHEREUM_MAINNET_ALM_PROXY
+    SPARK_BASE = SPARK_BASE_ALM_PROXY
+    SPARK_ARBITRUM = SPARK_ARBITRUM_ALM_PROXY
+    SPARK_UNICHAIN = SPARK_UNICHAIN_ALM_PROXY
+    SPARK_OPTIMISM = SPARK_OPTIMISM_ALM_PROXY
+    SPARK_AVALANCHE = SPARK_AVALANCHE_ALM_PROXY
+
+    GROVE_ETHEREUM_MAINNET = GROVE_ETHEREUM_MAINNET_ALM_PROXY
+    GROVE_AVALANCHE = GROVE_AVALANCHE_ALM_PROXY
+    GROVE_BASE = GROVE_BASE_ALM_PROXY
+    GROVE_PLASMA = GROVE_PLASMA_ALM_PROXY
+    GROVE_PLUME = GROVE_PLUME_ALM_PROXY
+    GROVE_MONAD = GROVE_MONAD_ALM_PROXY

{axis_synome-0.1.0.dev33 → axis_synome-0.1.0.dev35}/src/axis_synome/spec/asc/entities/networks.py

@@ -9,6 +9,8 @@ class Network(Enum):
     UNICHAIN = "Unichain"
     AVALANCHE = "Avalanche"
     PLASMA = "Plasma"
+    PLUME = "Plume"
+    MONAD = "Monad"
 
 
 # L2 networks: all networks that are not Ethereum mainnet.

{axis_synome-0.1.0.dev33 → axis_synome-0.1.0.dev35}/src/axis_synome/spec/asc/entities/primes.py

@@ -39,6 +39,8 @@ class PrimeAgent(Enum):
             Network.AVALANCHE,
             Network.BASE,
             Network.ETHEREUM_MAINNET,
+            Network.OPTIMISM,
+            Network.UNICHAIN,
         },
     )
     GROVE = PrimeAgentData(
@@ -51,6 +53,8 @@ class PrimeAgent(Enum):
             Network.BASE,
             Network.ETHEREUM_MAINNET,
             Network.PLASMA,
+            Network.PLUME,
+            Network.MONAD,
         },
     )
     KEEL = PrimeAgentData(

axis_synome-0.1.0.dev35/src/axis_synome/spec_validator/check_source_uuids.py

@@ -0,0 +1,378 @@
+"""Verify each ``:source_uuid:`` in spec docstrings resolves to an ``id`` in the
+Atlas ``content/`` tree (one ``document.md`` per Atlas section, with YAML
+frontmatter carrying ``id: <uuid>``).
+"""
+
+# ruff: noqa: T201 -- CLI entry point legitimately prints to stdout/stderr.
+
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import re
+import sys
+from collections import defaultdict
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+# Canonical 8-4-4-4-12 hex UUID. Case-insensitive; we lowercase before compare.
+_UUID_RE = re.compile(
+    r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"
+)
+
+# Generic reST field at the start of a docstring line: ``:name: value``.
+# ``name`` is restricted to identifier-shaped tokens so we don't match URLs etc.
+_FIELD_LINE_RE = re.compile(r"^:([A-Za-z][A-Za-z0-9_-]*):\s*(.*)$")
+
+# Allowlist of recognised docstring field names. Anything else triggers a
+# warning so typos and unintended drift surface early.
+ALLOWED_DOCSTRING_FIELDS: frozenset[str] = frozenset({"source_uuid"})
+
+# YAML frontmatter ``id:`` field. We don't pull in a YAML parser for one line;
+# the field is always emitted as ``id: <uuid>`` by the Atlas decompose tool.
+_FRONTMATTER_ID_RE = re.compile(r"^id:\s+(" + _UUID_RE.pattern + r")\s*$")
+
+# Defaults derived from this file's location so the CLI works from any cwd.
+# `parents` indices: [0]=spec_validator, [1]=axis_synome (under src),
+# [2]=src, [3]=axis_synome (package dir), [4]=python, [5]=repo root.
+_HERE = Path(__file__).resolve()
+DEFAULT_SPEC_ROOT: Path = _HERE.parents[1] / "spec"
+DEFAULT_CONTENT_ROOT: Path = _HERE.parents[5] / "content"
+
+
+@dataclass(frozen=True)
+class SpecRef:
+    """A single ``:source_uuid:`` reference extracted from a spec file."""
+
+    path: Path
+    lineno: int
+    symbol: str
+    uuid: str  # lowercased
+
+
+@dataclass(frozen=True)
+class FieldWarning:
+    """A non-fatal issue extracted alongside the spec references."""
+
+    path: Path
+    lineno: int
+    message: str
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    spec_refs: list[SpecRef]
+    atlas_uuids: frozenset[str]  # lowercased
+    missing: dict[str, list[SpecRef]]  # uuid -> refs that point at it
+    warnings: list[FieldWarning]
+
+
+# --------------------------------------------------------------------------- #
+# Spec-side extraction
+# --------------------------------------------------------------------------- #
+
+
+def _iter_spec_files(spec_root: Path) -> Iterator[Path]:
+    yield from sorted(p for p in spec_root.rglob("*.py") if "__pycache__" not in p.parts)
+
+
+def _process_docstring(
+    docstring: str,
+    *,
+    path: Path,
+    base_lineno: int,
+    symbol: str,
+) -> tuple[list[SpecRef], list[FieldWarning]]:
+    """Extract every reST ``:name: value`` field from a docstring.
+
+    For ``:source_uuid:`` we yield a :class:`SpecRef` (with a malformed-UUID
+    warning if the value isn't canonical 8-4-4-4-12 hex). For any other field
+    name we yield an "unknown field" warning so the allowlist in
+    :data:`ALLOWED_DOCSTRING_FIELDS` stays the single point of truth.
+    """
+    refs: list[SpecRef] = []
+    warnings: list[FieldWarning] = []
+    for offset, raw in enumerate(docstring.splitlines()):
+        line = raw.strip()
+        match = _FIELD_LINE_RE.match(line)
+        if not match:
+            continue
+        name = match.group(1)
+        value = match.group(2).strip()
+        lineno = base_lineno + offset
+
+        if name == "source_uuid":
+            uuid_match = _UUID_RE.fullmatch(value)
+            if uuid_match is None:
+                warnings.append(
+                    FieldWarning(
+                        path=path,
+                        lineno=lineno,
+                        message=(
+                            f"':source_uuid:' value is not a canonical 8-4-4-4-12 "
+                            f"hex UUID: {value!r}"
+                        ),
+                    )
+                )
+                continue
+            refs.append(
+                SpecRef(
+                    path=path,
+                    lineno=lineno,
+                    symbol=symbol,
+                    uuid=value.lower(),
+                )
+            )
+            continue
+
+        if name not in ALLOWED_DOCSTRING_FIELDS:
+            warnings.append(
+                FieldWarning(
+                    path=path,
+                    lineno=lineno,
+                    message=(
+                        f"unknown docstring field ':{name}:' — "
+                        f"allowed fields: {sorted(ALLOWED_DOCSTRING_FIELDS)}"
+                    ),
+                )
+            )
+
+    return refs, warnings
+
+
+def _docstring_node(body: list[ast.stmt]) -> tuple[str, int] | None:
+    """Return ``(docstring, lineno)`` if first stmt is a bare string-literal Expr."""
+    if not body:
+        return None
+    first = body[0]
+    if (
+        isinstance(first, ast.Expr)
+        and isinstance(first.value, ast.Constant)
+        and isinstance(first.value.value, str)
+    ):
+        return first.value.value, first.value.lineno
+    return None
+
+
+def _trailing_const_docstrings(body: list[ast.stmt]) -> Iterator[tuple[str, str, int]]:
+    """Yield ``(target_name, docstring, lineno)`` for ``X: Final[...] = v`` followed by ``\"\"\"...\"\"\"``.
+
+    Mirrors :class:`SpecChecker._validate_constant_docstrings` but only needs
+    the ``(name, docstring)`` pairs — we don't enforce structure here.
+    """
+    for prev, curr in zip(body, body[1:], strict=False):
+        if not (
+            isinstance(curr, ast.Expr)
+            and isinstance(curr.value, ast.Constant)
+            and isinstance(curr.value.value, str)
+        ):
+            continue
+        target_name: str | None = None
+        if isinstance(prev, ast.AnnAssign) and isinstance(prev.target, ast.Name):
+            target_name = prev.target.id
+        elif (
+            isinstance(prev, ast.Assign)
+            and len(prev.targets) == 1
+            and isinstance(prev.targets[0], ast.Name)
+        ):
+            target_name = prev.targets[0].id
+        if target_name is not None:
+            yield target_name, curr.value.value, curr.value.lineno
+
+
+def extract_spec_refs(path: Path) -> tuple[list[SpecRef], list[FieldWarning]]:
+    """Extract every ``:source_uuid:`` reference (and field warnings) from one spec file."""
+    source = path.read_text(encoding="utf-8")
+    try:
+        tree = ast.parse(source, filename=str(path))
+    except SyntaxError as exc:
+        return [], [
+            FieldWarning(path=path, lineno=exc.lineno or 0, message=f"syntax error: {exc.msg}")
+        ]
+
+    refs: list[SpecRef] = []
+    warnings: list[FieldWarning] = []
+
+    module_doc = _docstring_node(tree.body)
+    if module_doc is not None:
+        text, lineno = module_doc
+        r, w = _process_docstring(text, path=path, base_lineno=lineno, symbol="<module>")
+        refs.extend(r)
+        warnings.extend(w)
+
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            doc = _docstring_node(node.body)
+            if doc is not None:
+                text, lineno = doc
+                r, w = _process_docstring(text, path=path, base_lineno=lineno, symbol=node.name)
+                refs.extend(r)
+                warnings.extend(w)
+        if isinstance(node, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            for name, text, lineno in _trailing_const_docstrings(list(node.body)):
+                r, w = _process_docstring(text, path=path, base_lineno=lineno, symbol=name)
+                refs.extend(r)
+                warnings.extend(w)
+
+    return refs, warnings
+
+
+# --------------------------------------------------------------------------- #
+# Atlas-side extraction
+# --------------------------------------------------------------------------- #
+
+
+def extract_atlas_uuids(content_root: Path) -> frozenset[str]:
+    """Extract ``id`` UUIDs from YAML frontmatter of every ``document.md`` under
+    ``content_root``. ``_index.md`` files (navigation only) are skipped.
+    """
+    uuids: set[str] = set()
+    for path in sorted(content_root.rglob("document.md")):
+        with path.open(encoding="utf-8") as fh:
+            if fh.readline().rstrip("\r\n") != "---":
+                continue
+            for raw in fh:
+                line = raw.rstrip("\r\n")
+                if line == "---":
+                    break
+                match = _FRONTMATTER_ID_RE.match(line)
+                if match:
+                    uuids.add(match.group(1).lower())
+                    break
+    return frozenset(uuids)
+
+
+# --------------------------------------------------------------------------- #
+# Orchestration
+# --------------------------------------------------------------------------- #
+
+
+def check(
+    spec_root: Path,
+    content_root: Path | None,
+) -> CheckResult:
+    """Run extraction on both sides and compute the missing / warning sets.
+
+    If ``content_root`` is ``None`` the Atlas side is treated as empty and no
+    "missing" entries are produced — callers decide whether that's an error.
+    """
+    spec_refs: list[SpecRef] = []
+    warnings: list[FieldWarning] = []
+    for path in _iter_spec_files(spec_root):
+        r, w = extract_spec_refs(path)
+        spec_refs.extend(r)
+        warnings.extend(w)
+
+    by_uuid: dict[str, list[SpecRef]] = defaultdict(list)
+    for ref in spec_refs:
+        by_uuid[ref.uuid].append(ref)
+
+    # Duplicate-UUID across distinct *files* → warning. Multiple symbols in
+    # the same module pointing at the same Atlas section is the natural pattern
+    # (e.g. an arithmetic formula and its boolean predicate variant); only
+    # cross-file reuse is suspicious enough to surface.
+    for uuid, refs in by_uuid.items():
+        files = {r.path for r in refs}
+        if len(files) > 1:
+            sample = refs[0]
+            others = [r for r in refs if r.path != sample.path]
+            other_locations = ", ".join(f"{r.path}:{r.lineno}" for r in others)
+            warnings.append(
+                FieldWarning(
+                    path=sample.path,
+                    lineno=sample.lineno,
+                    message=(
+                        f"UUID {uuid} reused across distinct files (also at {other_locations})"
+                    ),
+                )
+            )
+
+    if content_root is None:
+        atlas_uuids: frozenset[str] = frozenset()
+        missing: dict[str, list[SpecRef]] = {}
+    else:
+        atlas_uuids = extract_atlas_uuids(content_root)
+        missing = {uuid: refs for uuid, refs in by_uuid.items() if uuid not in atlas_uuids}
+
+    return CheckResult(
+        spec_refs=spec_refs,
+        atlas_uuids=atlas_uuids,
+        missing=missing,
+        warnings=warnings,
+    )
+
+
+# --------------------------------------------------------------------------- #
+# CLI
+# --------------------------------------------------------------------------- #
+
+
+def _format_missing(missing: dict[str, list[SpecRef]]) -> str:
+    lines = ["ERROR: spec :source_uuid: values not found in the Atlas content tree:"]
+    for uuid in sorted(missing):
+        refs = missing[uuid]
+        lines.append(f"  {uuid}")
+        for ref in refs:
+            lines.append(f"    {ref.path}:{ref.lineno} ({ref.symbol})")
+    return "\n".join(lines)
+
+
+def _emit_map(result: CheckResult, path: Path) -> None:
+    payload = {
+        "spec_to_atlas": [
+            {
+                "uuid": ref.uuid,
+                "spec_path": str(ref.path),
+                "lineno": ref.lineno,
+                "symbol": ref.symbol,
+            }
+            for ref in sorted(result.spec_refs, key=lambda r: (str(r.path), r.lineno))
+        ],
+    }
+    path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="check-source-uuids",
+        description="Verify spec :source_uuid: references resolve to UUIDs in the Atlas content tree.",
+    )
+    parser.add_argument(
+        "--emit-map",
+        type=Path,
+        default=None,
+        help="Optional path to write a JSON spec↔atlas map.",
+    )
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    if not DEFAULT_SPEC_ROOT.is_dir():
+        print(f"ERROR: spec root not found: {DEFAULT_SPEC_ROOT}", file=sys.stderr)
+        return 2
+    if not DEFAULT_CONTENT_ROOT.is_dir():
+        print(f"ERROR: Atlas content tree not found: {DEFAULT_CONTENT_ROOT}", file=sys.stderr)
+        return 2
+
+    result = check(DEFAULT_SPEC_ROOT, DEFAULT_CONTENT_ROOT)
+
+    for warn in result.warnings:
+        print(f"WARN: {warn.path}:{warn.lineno}: {warn.message}", file=sys.stderr)
+
+    if args.emit_map is not None:
+        _emit_map(result, args.emit_map)
+
+    if result.missing:
+        print(_format_missing(result.missing), file=sys.stderr)
+        return 1
+
+    print(
+        f"OK: all {len(result.spec_refs)} spec :source_uuid: values "
+        f"({len({r.uuid for r in result.spec_refs})} unique) "
+        f"resolve to documents under {DEFAULT_CONTENT_ROOT}."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{axis_synome-0.1.0.dev33 → axis_synome-0.1.0.dev35}/src/axis_synome.egg-info/PKG-INFO

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