luplo.core.history
==================

.. py:module:: luplo.core.history

.. autoapi-nested-parse::

   Operations for the items_history table.

   Every meaningful change to an item (content edit, sync update) is recorded
   here with before/after snapshots, a diff summary, and a semantic impact
   classification.  This powers the ``luplo_history_query`` MCP tool and the
   future compliance audit view.



Functions
---------

.. autoapisummary::

   luplo.core.history.record_history
   luplo.core.history.query_history


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

.. py:function:: record_history(conn: psycopg.AsyncConnection[Any], *, item_id: str, version: int, changed_by: str, content_before: str | None = None, content_after: str | None = None, content_hash_before: str | None = None, content_hash_after: str | None = None, diff_summary: str | None = None, semantic_impact: str | None = None, source_event_id: str | None = None) -> luplo.core.models.HistoryEntry
   :async:


   Record a change to an item.

   :param conn: Async psycopg connection.
   :param item_id: The item that was changed.
   :param version: Monotonically increasing version number for this item.
   :param changed_by: Actor ID of who made the change.
   :param content_before: Previous content snapshot (optional).
   :param content_after: New content snapshot (optional).
   :param content_hash_before: SHA256 of previous content (optional).
   :param content_hash_after: SHA256 of new content (optional).
   :param diff_summary: Human-readable change summary (optional).
   :param semantic_impact: Change classification — ``numeric_change``,
                           ``rule_addition``, ``rule_removal``, ``rewording``,
                           ``formatting``, ``typo_fix``, ``structural`` (optional).
   :param source_event_id: External event ID for idempotency (optional).

   :returns: The recorded ``HistoryEntry`` with auto-generated ``id``.


.. py:function:: query_history(conn: psycopg.AsyncConnection[Any], *, project_id: str | None = None, item_id: str | None = None, since: datetime.datetime | None = None, semantic_impacts: list[str] | None = None, limit: int = 50) -> list[luplo.core.models.HistoryEntry]
   :async:


   Query change history with optional filters.

   At least one of ``project_id`` or ``item_id`` should be provided;
   otherwise an unscoped query may return too many rows.

   :param conn: Async psycopg connection.
   :param project_id: Filter by project (requires JOIN to items).
   :param item_id: Filter by specific item.
   :param since: Only return entries after this timestamp.
   :param semantic_impacts: Filter by impact types (e.g.
                            ``["numeric_change", "rule_addition"]``).
   :param limit: Maximum rows (default 50).

   :returns: List of ``HistoryEntry`` ordered by ``changed_at DESC``.