mud_server.axis.grammar

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.

AxisRuleConfig.base_magnitude defaults to 0.0 for no_effect resolvers; payloads may omit the field for those axes.

Attributes

`VALID_RESOLVERS`
`REQUIRED_CHANNELS`

Classes

`AxisRuleConfig`	Configuration for one axis within one interaction type.
`ChatGrammar`	Resolution rules for the `chat` stimulus type.
`ResolutionGrammar`	Top-level container for all resolution rules in a world.

Functions

parse_resolution_grammar_payload(*, raw, source)

Parse and validate one resolution grammar mapping payload.

Module Contents

mud_server.axis.grammar.VALID_RESOLVERS: frozenset[str]

mud_server.axis.grammar.REQUIRED_CHANNELS: frozenset[str]

class mud_server.axis.grammar.AxisRuleConfig[source]

Configuration for one axis within one interaction type.

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.

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.

resolver: str

base_magnitude: float = 0.0

class mud_server.axis.grammar.ChatGrammar[source]

Resolution rules for the chat stimulus type.

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).

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.

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

channel_multipliers: dict[str, float]

min_gap_threshold: float

axes: dict[str, AxisRuleConfig]

class mud_server.axis.grammar.ResolutionGrammar[source]

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.

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.

chat: Rules governing axis mutations produced by chat interactions.

version: str

chat: ChatGrammar

mud_server.axis.grammar.parse_resolution_grammar_payload(*, raw, source)[source]

Parse and validate one resolution grammar mapping payload.

Parameters:

raw (object) – Untrusted payload object expected to be a top-level mapping.
source (str) – Human-readable source label used in validation errors.

Returns:

A fully-constructed immutable ResolutionGrammar.

Raises:

ValueError – On schema validation failure.

Return type:

ResolutionGrammar