mud_server.axis.grammar
=======================

.. py:module:: mud_server.axis.grammar

.. autoapi-nested-parse::

   Resolution grammar parser and typed rule dataclasses.

   The resolution grammar is a deterministic rules payload for axis mutations.
   In canonical runtime mode, this payload is resolved from activated DB policy
   variants (``axis_bundle.content.resolution``) and parsed via
   ``parse_resolution_grammar_payload``.

   Design notes:
   1. All dataclasses are frozen (immutable after parse).
   2. This module is payload-based and does not read policy files from disk.
   3. File-backed loading remains available only in
      ``mud_server.axis.migration_file_loader`` for explicit migration/testing
      workflows.
   4. ``AxisRuleConfig.base_magnitude`` defaults to ``0.0`` for ``no_effect``
      resolvers; payloads may omit the field for those axes.



Attributes
----------

.. autoapisummary::

   mud_server.axis.grammar.VALID_RESOLVERS
   mud_server.axis.grammar.REQUIRED_CHANNELS


Classes
-------

.. autoapisummary::

   mud_server.axis.grammar.AxisRuleConfig
   mud_server.axis.grammar.ChatGrammar
   mud_server.axis.grammar.ResolutionGrammar


Functions
---------

.. autoapisummary::

   mud_server.axis.grammar.parse_resolution_grammar_payload


Module Contents
---------------

.. py:data:: VALID_RESOLVERS
   :type:  frozenset[str]

.. py:data:: REQUIRED_CHANNELS
   :type:  frozenset[str]

.. py:class:: AxisRuleConfig

   Configuration for one axis within one interaction type.

   .. attribute:: resolver

      Name of the resolver function — one of
      ``"dominance_shift"``, ``"shared_drain"``, or
      ``"no_effect"``.  The axis engine looks up the
      callable via the resolver registry in ``engine.py``.

   .. attribute:: base_magnitude

      Scaling factor fed into the resolver (e.g. ``0.03``
      for demeanor, ``0.01`` for health).  Defaults to
      ``0.0`` for ``no_effect`` axes; the YAML may omit the
      field entirely for those axes.


   .. py:attribute:: resolver
      :type:  str


   .. py:attribute:: base_magnitude
      :type:  float
      :value: 0.0



.. py:class:: ChatGrammar

   Resolution rules for the ``chat`` stimulus type.

   .. attribute:: channel_multipliers

      Per-channel scaling factors applied to every axis
      delta.  Keys are channel names (``"say"``,
      ``"yell"``, ``"whisper"``); values are positive
      floats (e.g. ``1.5`` for yell, ``0.5`` for
      whisper).

   .. attribute:: min_gap_threshold

      Minimum absolute score difference below which
      ``dominance_shift`` produces no delta.  Two
      similarly-matched characters interact without
      either gaining social ground.  ``shared_drain``
      (health) ignores this threshold — social cost is
      universal regardless of demeanor gap.

   .. attribute:: axes

      Mapping from axis name to its
      :class:`AxisRuleConfig`.  Every axis registered
      in the world should appear here (explicitly, even
      as ``no_effect``), so the engine can assert full
      coverage.


   .. py:attribute:: channel_multipliers
      :type:  dict[str, float]


   .. py:attribute:: min_gap_threshold
      :type:  float


   .. py:attribute:: axes
      :type:  dict[str, AxisRuleConfig]


.. py:class:: ResolutionGrammar

   Top-level container for all resolution rules in a world.

   Currently only the ``chat`` interaction type is defined.  Future stimulus
   types (``environmental``, ``physical``, ``economic``) will add new
   attributes here alongside their own YAML blocks.

   .. attribute:: version

      Schema version string read from the YAML file (e.g. ``"1.0"``).
      Stored on ``chat.mechanical_resolution`` ledger events for
      audit and replay traceability.

   .. attribute:: chat

      Rules governing axis mutations produced by chat interactions.


   .. py:attribute:: version
      :type:  str


   .. py:attribute:: chat
      :type:  ChatGrammar


.. py:function:: parse_resolution_grammar_payload(*, raw, source)

   Parse and validate one resolution grammar mapping payload.

   :param raw: Untrusted payload object expected to be a top-level mapping.
   :param source: Human-readable source label used in validation errors.

   :returns: A fully-constructed immutable :class:`ResolutionGrammar`.

   :raises ValueError: On schema validation failure.