build_tools.syllable_walk_web.api.walker_common
===============================================

.. py:module:: build_tools.syllable_walk_web.api.walker_common

.. autoapi-nested-parse::

   Shared stateless helper functions for walker API handlers.

   This module contains request-coercion and comparison helpers that do not need
   filesystem access or mutation side effects. It exists to reduce the size and
   cognitive load of ``api/walker.py`` while preserving existing endpoint
   contracts.



Functions
---------

.. autoapisummary::

   build_tools.syllable_walk_web.api.walker_common.is_sha256_hex
   build_tools.syllable_walk_web.api.walker_common.reach_cache_verification_from_read
   build_tools.syllable_walk_web.api.walker_common.resolve_patch_state
   build_tools.syllable_walk_web.api.walker_common.coerce_optional_constraint_int
   build_tools.syllable_walk_web.api.walker_common.compute_patch_comparison


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

.. py:function:: is_sha256_hex(value)

   Return ``True`` when value is a lowercase 64-character SHA-256 hash.


.. py:function:: reach_cache_verification_from_read(*, cache_status, cache_message, input_hash, output_hash)

   Map reach-cache read outcomes to verification status and reason.

   This preserves the user-facing semantics consumed by the Walker UI:
   - cache hit + valid hashes => ``verified``
   - cache hit + missing hashes => ``error``
   - invalid/miss/none/error map to deterministic reason strings


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

   Resolve request ``patch`` to ``("a"|"b", PatchState)``.

   :param body: Request payload that may include ``patch``.
   :param state: Global server state containing patch A and patch B.

   :returns: Tuple of ``(patch_key, patch_state)`` when valid; otherwise ``None``.


.. py:function:: coerce_optional_constraint_int(body, field_name, *, default)

   Coerce one optional integer constraint from request payload.

   Semantics:
   - Missing field: use provided ``default``.
   - Explicit ``null``: disable this constraint (return ``None``).
   - Provided value: coerce to ``int`` or return deterministic error.


.. py:function:: compute_patch_comparison(*, patch_a_manifest_hash, patch_b_manifest_hash)

   Compute Patch A/B manifest-hash relation and policy signal.