build_tools.syllable_walk_web.api.walker_lock
=============================================

.. py:module:: build_tools.syllable_walk_web.api.walker_lock

.. autoapi-nested-parse::

   Lock-related helper functions for walker API handlers.

   This module isolates cooperative session-lock logic used by walker endpoints.
   It keeps the lock behavior in one place so `api/walker.py` can focus on
   endpoint orchestration.

   Important:
   - These helpers implement single-user multi-tab consistency behavior.
   - They are not an authentication or security boundary.



Functions
---------

.. autoapisummary::

   build_tools.syllable_walk_web.api.walker_lock.coerce_lock_holder_id
   build_tools.syllable_walk_web.api.walker_lock.lock_conflict_error
   build_tools.syllable_walk_web.api.walker_lock.enforce_active_session_lock
   build_tools.syllable_walk_web.api.walker_lock.clear_active_session_context


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

.. py:function:: coerce_lock_holder_id(body)

   Extract optional ``lock_holder_id`` from request payload.

   :param body: Request JSON payload.

   :returns: Tuple of ``(holder_id, error_message)``.
             ``holder_id`` is stripped when present and valid.
             ``error_message`` is populated when input is present but invalid.


.. py:function:: lock_conflict_error(*, active_session_id, lock_payload)

   Build one deterministic lock-conflict response payload.


.. py:function:: enforce_active_session_lock(body, state)

   Enforce active-session lock ownership for mutating requests.

   Behavior:
   - If no active session lock context exists, request is allowed.
   - If active lock exists, caller must provide matching ``lock_holder_id``.
   - Lock is refreshed via cooperative lock service when holder matches.


.. py:function:: clear_active_session_context(state)

   Clear active loaded-session metadata from server state.