build_tools.syllable_walk_web.services.session_paths
====================================================

.. py:module:: build_tools.syllable_walk_web.services.session_paths

.. autoapi-nested-parse::

   Path helpers for walker IPC session and patch-output artifacts.

   This module centralises filesystem path conventions for upcoming Patch A/B
   session persistence features. It intentionally contains no IO side effects:
   callers decide when to create directories or write files.



Attributes
----------

.. autoapisummary::

   build_tools.syllable_walk_web.services.session_paths.PatchKey
   build_tools.syllable_walk_web.services.session_paths.PatchOutputKind
   build_tools.syllable_walk_web.services.session_paths.PATCH_KEYS
   build_tools.syllable_walk_web.services.session_paths.PATCH_OUTPUT_KINDS


Functions
---------

.. autoapisummary::

   build_tools.syllable_walk_web.services.session_paths.resolve_sessions_base
   build_tools.syllable_walk_web.services.session_paths.run_ipc_dir
   build_tools.syllable_walk_web.services.session_paths.patch_output_sidecar_path
   build_tools.syllable_walk_web.services.session_paths.session_file_path


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

.. py:data:: PatchKey

.. py:data:: PatchOutputKind

.. py:data:: PATCH_KEYS
   :type:  tuple[PatchKey, Ellipsis]
   :value: ('a', 'b')


.. py:data:: PATCH_OUTPUT_KINDS
   :type:  tuple[PatchOutputKind, Ellipsis]
   :value: ('walks', 'candidates', 'selections', 'package')


.. py:function:: resolve_sessions_base(*, output_base, configured_sessions_base = None)

   Resolve the directory used for persisted walker session files.

   Resolution policy:

   1. Use ``configured_sessions_base`` when provided.
   2. Otherwise derive ``<output_base>/sessions``.

   :param output_base: Active output root configured for this server instance.
   :param configured_sessions_base: Optional explicit sessions directory override.

   :returns: Normalized absolute path for session file storage.


.. py:function:: run_ipc_dir(run_dir)

   Return the canonical IPC subdirectory for one run directory.


.. py:function:: patch_output_sidecar_path(*, run_dir, patch, artifact_kind, schema_version = 1)

   Build the canonical path for one patch-output sidecar artifact.

   Example::
       ``<run_dir>/ipc/patch_a_walks.v1.json``


.. py:function:: session_file_path(*, session_id, output_base, configured_sessions_base = None)

   Build the canonical filename for one saved dual-patch session.

   :param session_id: Opaque session identifier.
   :param output_base: Active output root configured for this server instance.
   :param configured_sessions_base: Optional explicit sessions directory override.

   :returns: Absolute path to ``<sessions_base>/<session_id>.json``.