mud_server.services.policy.validation
=====================================

.. py:module:: mud_server.services.policy.validation

.. autoapi-nested-parse::

   Canonical policy validation and upsert workflows.

   This module owns contract-level validation and validate-before-write behavior.
   Storage repositories remain persistence-only; this layer enforces business
   rules that define valid canonical policy objects.



Functions
---------

.. autoapisummary::

   mud_server.services.policy.validation.parse_policy_id
   mud_server.services.policy.validation.list_policies
   mud_server.services.policy.validation.get_policy
   mud_server.services.policy.validation.validate_policy_variant
   mud_server.services.policy.validation.upsert_policy_variant
   mud_server.services.policy.validation.is_policy_variant_unchanged


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

.. py:function:: parse_policy_id(policy_id)

   Parse canonical ``policy_type:namespace:policy_key`` identity.

   :raises PolicyServiceError: When the identity format is invalid or policy type
       is not supported by canonical policy APIs.


.. py:function:: list_policies(*, policy_type, namespace, status)

   List canonical policy variants with optional filter constraints.


.. py:function:: get_policy(*, policy_id, variant)

   Get a canonical policy row by id and optional variant selector.


.. py:function:: validate_policy_variant(*, policy_id, variant, schema_version, policy_version, status, content, validated_by)

   Validate one policy payload and persist validation-run history.


.. py:function:: upsert_policy_variant(*, policy_id, variant, schema_version, policy_version, status, content, updated_by)

   Validate then upsert one canonical policy variant row.

   The write path enforces the invariant that invalid payloads never reach
   canonical variant storage.


.. py:function:: is_policy_variant_unchanged(*, existing_row, schema_version = None, policy_version, status, content)

   Return whether the existing variant row already matches provided payload.