luplo.core.history

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

record_history(→ luplo.core.models.HistoryEntry)

Record a change to an item.

query_history(→ list[luplo.core.models.HistoryEntry])

Query change history with optional filters.

Module Contents

async luplo.core.history.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

Record a change to an item.

Parameters:

  • conn – Async psycopg connection.

  • item_id – The item that was changed.

  • version – Monotonically increasing version number for this item.

  • changed_by – Actor ID of who made the change.

  • content_before – Previous content snapshot (optional).

  • content_after – New content snapshot (optional).

  • content_hash_before – SHA256 of previous content (optional).

  • content_hash_after – SHA256 of new content (optional).

  • diff_summary – Human-readable change summary (optional).

  • semantic_impact – Change classification — numeric_change, rule_addition, rule_removal, rewording, formatting, typo_fix, structural (optional).

  • source_event_id – External event ID for idempotency (optional).

Returns:

The recorded HistoryEntry with auto-generated id.

async luplo.core.history.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]

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.

Parameters:

  • conn – Async psycopg connection.

  • project_id – Filter by project (requires JOIN to items).

  • item_id – Filter by specific item.

  • since – Only return entries after this timestamp.

  • semantic_impacts – Filter by impact types (e.g. ["numeric_change", "rule_addition"]).

  • limit – Maximum rows (default 50).

Returns:

List of HistoryEntry ordered by changed_at DESC.