httk.workflow.manifests
=======================

.. py:module:: httk.workflow.manifests

.. autoapi-nested-parse::

   Deterministic signed project manifests.



Attributes
----------

.. autoapisummary::

   httk.workflow.manifests.MAINTENANCE_LOCK_FILE
   httk.workflow.manifests.MAINTENANCE_LOCK_MAX_AGE_SECONDS


Classes
-------

.. autoapisummary::

   httk.workflow.manifests.MaintenanceLock


Functions
---------

.. autoapisummary::

   httk.workflow.manifests.payload_file_records
   httk.workflow.manifests.read_maintenance_lock
   httk.workflow.manifests.release_maintenance_lock
   httk.workflow.manifests.workspace_maintenance_guard
   httk.workflow.manifests.verify_legacy_manifest
   httk.workflow.manifests.verify_manifest


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

.. py:data:: MAINTENANCE_LOCK_FILE
   :value: 'maintenance.lock'


.. py:data:: MAINTENANCE_LOCK_MAX_AGE_SECONDS
   :value: 86400


.. py:function:: payload_file_records(root)

   Return the deterministic records of one job payload, minus runner scratch.

   A payload's runner-private entries — attempt control, logs, and job state —
   are excluded from every seal record exactly as they are from a payload
   digest, so publishing an outcome never changes a sealed payload's records.


.. py:class:: MaintenanceLock

   Record the holder of one workspace maintenance lock.

   :param path: Locate the lock file.
   :param pid: Record the holder process identifier, when readable.
   :param hostname: Record the holder host, when readable.
   :param created: Record the holder creation timestamp, when readable.
   :param readable: Mark whether the lock contents could be read.


   .. py:attribute:: path
      :type:  pathlib.Path


   .. py:attribute:: pid
      :type:  int | None


   .. py:attribute:: hostname
      :type:  str | None


   .. py:attribute:: created
      :type:  str | None


   .. py:attribute:: readable
      :type:  bool
      :value: True



   .. py:property:: age_seconds
      :type: float | None


      Age of the lock, or ``None`` when its timestamp is unusable.


   .. py:property:: local
      :type: bool


      Whether the recorded host is the host inspecting the lock.


   .. py:property:: dead
      :type: bool


      Whether a same-host holder process is known to be gone.


   .. py:method:: is_stale(*, max_age_seconds = MAINTENANCE_LOCK_MAX_AGE_SECONDS)

      Whether the lock can be reclaimed without operator confirmation.



   .. py:method:: describe()

      Describe the holder for an operator diagnostic.



.. py:function:: read_maintenance_lock(workspace)

   Describe the workspace maintenance lock, or ``None`` when it is absent.

   :param workspace: Locate the workspace whose lock to inspect.
   :return: The recorded lock, or ``None`` when no lock exists.


.. py:function:: release_maintenance_lock(workspace, *, force = False)

   Remove a stale, or with *force* any, maintenance lock and report it.

   :param workspace: Locate the workspace whose lock to remove.
   :param force: Permit removal of a lock that does not appear stale.
   :return: A human-readable removal result.
   :raises ValueError: If a live lock is protected by the default policy.


.. py:function:: workspace_maintenance_guard(workspace)

   Fence manager launches while a project snapshot is inspected.

   :param workspace: Lock and inspect this workspace around the guarded work.
   :return: A context manager that holds the maintenance lock.
   :raises ValueError: If the workspace is already maintained or not quiescent.


.. py:function:: verify_legacy_manifest(root, path)

   Verify a legacy manifest without modifying its project tree.

   :param root: Locate the tree the manifest should describe.
   :param path: Locate the legacy manifest to verify.
   :return: Whether the legacy tree records and signature verify.


.. py:function:: verify_manifest(project = None, *, manifest = None, trusted_keys = None)

   Auto-detect a v2 or legacy manifest and verify it against its trust anchors.

   The trust anchor is the key pinned in ``project.json`` — never the key the
   manifest being verified names in its own header — plus any key passed in
   *trusted_keys*, as a recorded value or as the path of a ``*.pub`` file.

   :param project: Locate the project to discover and verify.
   :param manifest: Select a manifest path instead of the project default.
   :param trusted_keys: Add explicit trust anchors to the project keys.
   :return: The detailed verification verdict.
   :raises ValueError: If no project or usable manifest exists.