nl2data-semantic-catalog-postgres 0.1.0__py3-none-any.whl

nl2data_semantic_catalog_postgres/errors.py

@@ -0,0 +1,188 @@
+"""Normalized safe errors for the PostgreSQL semantic catalog.
+
+Backend failures are converted into deterministic, serializable error
+records.  Records carry only a stable code, category, bounded message, and
+redacted details - never DSNs, credentials, raw backend exception text, or
+native driver objects.  Unavailability and timeouts are retryable; schema
+mismatches, conflicts, authorization failures, envelope rejections,
+fingerprint mismatches, and bound violations are not, because retrying them
+without a host decision cannot succeed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import StrEnum
+from typing import Any
+
+from nl2data._redact import REDACTED_VALUE, redact_key_value
+from nl2data.errors import ErrorCategory, ErrorCode, ErrorRecord
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from .envelope import EnvelopeRejectedError
+
+
+class SemanticCatalogErrorCode(StrEnum):
+    """Stable machine-readable catalog error codes."""
+
+    CATALOG_UNAVAILABLE = "CATALOG_UNAVAILABLE"
+    CATALOG_TIMEOUT = "CATALOG_TIMEOUT"
+    SCHEMA_MISMATCH = "SCHEMA_MISMATCH"
+    CONFLICT = "CONFLICT"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    ENVELOPE_REJECTED = "ENVELOPE_REJECTED"
+    FINGERPRINT_MISMATCH = "FINGERPRINT_MISMATCH"
+    BOUNDS_EXCEEDED = "BOUNDS_EXCEEDED"
+
+
+#: Codes that are safe to retry without changing the invocation.
+_RETRYABLE_CODES = frozenset(
+    {
+        SemanticCatalogErrorCode.CATALOG_UNAVAILABLE,
+        SemanticCatalogErrorCode.CATALOG_TIMEOUT,
+    }
+)
+
+#: Mapping onto the stable public error contract for public outcomes.
+_PUBLIC_CODE: dict[SemanticCatalogErrorCode, ErrorCode] = {
+    SemanticCatalogErrorCode.CATALOG_UNAVAILABLE: ErrorCode.STORE_UNAVAILABLE,
+    SemanticCatalogErrorCode.CATALOG_TIMEOUT: ErrorCode.STORE_TIMEOUT,
+    SemanticCatalogErrorCode.SCHEMA_MISMATCH: ErrorCode.UNSUPPORTED_SCHEMA_VERSION,
+    SemanticCatalogErrorCode.CONFLICT: ErrorCode.INVALID_TRANSITION,
+    SemanticCatalogErrorCode.UNAUTHORIZED: ErrorCode.METADATA_UNAUTHORIZED,
+    SemanticCatalogErrorCode.ENVELOPE_REJECTED: ErrorCode.INVALID_INPUT,
+    SemanticCatalogErrorCode.FINGERPRINT_MISMATCH: ErrorCode.INVALID_INPUT,
+    SemanticCatalogErrorCode.BOUNDS_EXCEEDED: ErrorCode.METADATA_BOUNDS_EXCEEDED,
+}
+
+
+class SemanticCatalogError(Exception):
+    """Structured catalog failure; safe to serialize.
+
+    The original driver exception may be retained for debugging but is
+    never part of the serialized record and never leaks through ``str``.
+    """
+
+    def __init__(
+        self,
+        code: SemanticCatalogErrorCode | str,
+        message: str,
+        *,
+        details: Mapping[str, Any] | None = None,
+        cause: BaseException | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = SemanticCatalogErrorCode(code)
+        self.message = message
+        self.details = dict(details or {})
+        self.cause = cause
+
+    @property
+    def category(self) -> ErrorCategory:
+        return ErrorCategory.ADAPTER
+
+    @property
+    def retryable(self) -> bool:
+        return self.code in _RETRYABLE_CODES
+
+    def safe_details(self) -> dict[str, str]:
+        """Scalar-only details; anything unsafe is replaced with a marker."""
+        return {str(k): redact_key_value(k, v) for k, v in self.details.items()}
+
+    def to_record(self) -> SemanticCatalogErrorRecord:
+        """Convert to the transport-neutral safe catalog error record."""
+        return SemanticCatalogErrorRecord(
+            code=self.code,
+            message=self.message,
+            retryable=self.retryable,
+            details=self.safe_details(),
+            cause_type=type(self.cause).__name__ if self.cause is not None else None,
+        )
+
+    def to_public_record(self) -> ErrorRecord:
+        """Convert to the public error contract used by host outcomes."""
+        return ErrorRecord(
+            code=_PUBLIC_CODE[self.code],
+            category=self.category,
+            message=self.message,
+            retryable=self.retryable,
+            details=self.safe_details(),
+            cause_type=type(self).__name__,
+        )
+
+
+class SemanticCatalogErrorRecord(BaseModel):
+    """Immutable normalized catalog error with redacted details only."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    code: SemanticCatalogErrorCode
+    message: str = Field(min_length=1, max_length=2000)
+    retryable: bool = False
+    details: dict[str, str] = Field(default_factory=dict, max_length=64)
+    cause_type: str | None = Field(default=None, max_length=256)
+
+    @field_validator("details")
+    @classmethod
+    def _sanitize_details(cls, value: Mapping[str, Any]) -> dict[str, str]:
+        sanitized: dict[str, str] = {}
+        for key, raw in value.items():
+            sanitized[key] = redact_key_value(key, raw)
+        return sanitized
+
+    def safe_dump(self) -> dict[str, Any]:
+        """Serialize with only stable, redacted fields - never raw backend text."""
+        return self.model_dump()
+
+
+def normalize_catalog_error(error: BaseException) -> SemanticCatalogError:
+    """Convert any exception into a normalized, safe catalog error.
+
+    Envelope rejections keep their bounded reason code; known driver failure
+    names become retryable unavailability/timeout errors; unknown exception
+    types become retryable unavailability errors with a redacted message so
+    backend internals never leak across the boundary.
+    """
+    if isinstance(error, SemanticCatalogError):
+        return error
+    if isinstance(error, EnvelopeRejectedError):
+        return SemanticCatalogError(
+            SemanticCatalogErrorCode.ENVELOPE_REJECTED,
+            "catalog artifact was rejected by safe envelope validation",
+            details={"reason": error.code, "cause_type": type(error).__name__},
+            cause=error,
+        )
+    name = type(error).__name__
+    if name in {"TimeoutError", "QueryCanceledError", "QueryCanceled", "Timeout"}:
+        return SemanticCatalogError(
+            SemanticCatalogErrorCode.CATALOG_TIMEOUT,
+            "catalog backend command timed out",
+            details={"cause_type": name},
+            cause=error,
+        )
+    if name in {
+        "OperationalError",
+        "InterfaceError",
+        "ConnectionError",
+        "PoolTimeout",
+        "PoolClosed",
+    }:
+        return SemanticCatalogError(
+            SemanticCatalogErrorCode.CATALOG_UNAVAILABLE,
+            "catalog backend is unreachable",
+            details={"cause_type": name},
+            cause=error,
+        )
+    if name in {"UniqueViolation", "IntegrityError", "SerializationFailure"}:
+        return SemanticCatalogError(
+            SemanticCatalogErrorCode.CONFLICT,
+            "catalog backend rejected a conflicting record",
+            details={"cause_type": name},
+            cause=error,
+        )
+    return SemanticCatalogError(
+        SemanticCatalogErrorCode.CATALOG_UNAVAILABLE,
+        REDACTED_VALUE,
+        details={"cause_type": name},
+        cause=error,
+    )

nl2data_semantic_catalog_postgres/fake_postgres/__init__.py

@@ -0,0 +1,53 @@
+"""In-memory PostgreSQL pool for the durable semantic catalog.
+
+Executes the exact statement set produced by :data:`SQL_TEMPLATES` against
+plain Python dictionaries, with per-connection transactions, row locks
+(``FOR UPDATE`` / conflict waits), a mutable server clock driving ``NOW()``,
+and failure injection so catalog behavior under backend outages can be
+tested without a real database or the optional driver.
+
+The fake mirrors the semantics the store relies on:
+
+- every ``connection()`` checkout is one transaction; ``commit`` publishes
+  mutations, ``rollback`` restores the pre-transaction values of touched
+  rows;
+- rows locked by one connection block conflicting statements from another
+  connection (bounded by the statement timeout), matching PostgreSQL row
+  locking closely enough for concurrency tests;
+- ``NOW()`` always reads the shared :class:`FakeClock`, so retention expiry
+  and cleanup can be advanced deterministically;
+- injected failure exceptions surface with the same class names the lazy
+  driver boundary classifies (``OperationalError``, ``TimeoutError``,
+  ``UniqueViolation``, ``SerializationFailure``), so the store's error
+  normalization path is exercised for real.
+
+Unrecognized statements fail loudly with ``AssertionError`` so template
+drift between the store and the fake is caught at the first test run.
+
+The pool is split by repository domain: shared driver, lock/key, and
+transaction infrastructure live in :mod:`.driver`, :mod:`.keys`, and
+:mod:`.pool`; statement handlers live in one module per repository domain
+and are wired together in :mod:`.registry`.
+"""
+
+from __future__ import annotations
+
+from .driver import (
+    FakeClock,
+    OperationalError,
+    PoolClosed,
+    SerializationFailure,
+    TimeoutError,
+    UniqueViolation,
+)
+from .pool import FakePostgresPool
+
+__all__ = [
+    "FakeClock",
+    "FakePostgresPool",
+    "OperationalError",
+    "PoolClosed",
+    "SerializationFailure",
+    "TimeoutError",
+    "UniqueViolation",
+]

nl2data_semantic_catalog_postgres/fake_postgres/driver.py

@@ -0,0 +1,209 @@
+"""Shared fake-driver infrastructure: exceptions, clock, transactions.
+
+The fake driver exception classes intentionally match the real psycopg
+class names so the store's class-name-first error classification works.
+Connections are one transaction each: mutations are published on commit
+and undone on rollback from the pre-transaction snapshots taken by
+``_touch``.
+"""
+
+from __future__ import annotations
+
+import builtins
+import contextlib
+import re
+import time
+from collections.abc import Iterator
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING, Any
+from uuid import uuid4
+
+if TYPE_CHECKING:
+    from .pool import FakePostgresPool
+
+#: Lock-key kind -> pool attribute holding the backing table (per instance).
+# Lives here (its only consumer) instead of keys.py so the driver->keys
+# import edge does not close a cycle with keys' TYPE_CHECKING driver import.
+_TABLE_ATTRS: dict[str, str] = {
+    "snapshots": "snapshots",
+    "snapshot_pointers": "snapshot_pointers",
+    "proposal_sets": "proposal_sets",
+    "assembly_drafts": "assembly_drafts",
+    "publications": "publications",
+    "accepted_manifests": "accepted_manifests",
+    "verification_evidence": "verification_evidence",
+    "publish_audits": "publish_audits",
+    "published_versions": "published_versions",
+    "supersession_edges": "supersession_edges",
+    "bundle_pointers": "bundle_pointers",
+    "bundle_history": "bundle_history",
+    "events": "events",
+    "publication_audit_evidence": "publication_audit_evidence",
+    "audit_entries": "audit_entries",
+}
+
+
+class OperationalError(Exception):
+    """Fake ``psycopg.OperationalError``: connection-level failure."""
+
+
+class TimeoutError(builtins.TimeoutError):  # noqa: A001 - fake driver class by design
+    """Fake ``psycopg.errors.QueryCanceled``: statement timed out."""
+
+
+class UniqueViolation(Exception):
+    """Fake ``psycopg.errors.UniqueViolation``: unique-key conflict."""
+
+
+class SerializationFailure(Exception):
+    """Fake ``psycopg.errors.SerializationFailure``: retryable conflict."""
+
+
+class PoolClosed(Exception):
+    """Fake ``psycopg_pool.PoolClosed``: pool was closed."""
+
+
+class _PassFailure:
+    """Internal marker: a statement slot that succeeds before a failure."""
+
+
+_SCHEMA_TOKEN = re.compile(r'"[A-Za-z0-9_]+"')
+
+
+def _normalize(sql: str) -> str:
+    """Collapse whitespace and mask the quoted schema for template matching."""
+    return _SCHEMA_TOKEN.sub('"S"', " ".join(sql.split()))
+
+
+def _as_dt(value: Any) -> datetime | None:
+    """Accept datetimes or ISO strings (as the store sends them)."""
+    if value is None or isinstance(value, datetime):
+        return value
+    return datetime.fromisoformat(str(value))
+
+
+def _monotonic() -> float:
+    return time.monotonic()
+
+
+class FakeClock:
+    """Mutable deterministic clock standing in for PostgreSQL ``NOW()``."""
+
+    def __init__(self, start: datetime | None = None) -> None:
+        self._now = start or datetime(2026, 1, 1, tzinfo=UTC)
+
+    def now(self) -> datetime:
+        """The current fake server time (timezone-aware, UTC)."""
+        return self._now
+
+    def advance(self, seconds: float) -> None:
+        """Move the clock forward by ``seconds`` (may be negative)."""
+        self._now += timedelta(seconds=seconds)
+
+    def set(self, value: datetime) -> None:
+        """Pin the clock to an exact instant (tests seed expiry)."""
+        self._now = value
+
+
+class _FakeConnection:
+    """One transaction; mutations are published on commit, undone on rollback."""
+
+    def __init__(self, pool: FakePostgresPool) -> None:
+        self._pool = pool
+        self._active = False
+        self._touched: dict[tuple[Any, ...], Any] = {}
+        self._owned_keys: set[tuple[Any, ...]] = set()
+        self.id = f"conn-{uuid4().hex[:12]}"
+
+    def cursor(self) -> _FakeCursor:
+        return _FakeCursor(self._pool, self, [], 0)
+
+    def execute(
+        self, sql: str, params: tuple[Any, ...] = (), timeout: float = 30.0
+    ) -> _FakeCursor:
+        return self._pool._execute(self, sql, params, timeout)
+
+    def commit(self) -> None:
+        """Publish the transaction; touched rows become visible to all."""
+        self._active = False
+        self._touched.clear()
+        self._pool._release(self)
+
+    def rollback(self) -> None:
+        """Undo every mutation this transaction made."""
+        if not self._active:
+            self._pool._release(self)
+            return
+        for key, previous in self._touched.items():
+            table = getattr(self._pool, _TABLE_ATTRS[key[0]])
+            table_key = key[1:]
+            if previous is None:
+                table.pop(table_key, None)
+            else:
+                table[table_key] = previous
+        self._active = False
+        self._touched.clear()
+        self._pool._release(self)
+
+    def _finish(self) -> None:
+        """Context-manager exit: drop any uncommitted transaction."""
+        if self._active:
+            self.rollback()
+        self._pool._release(self)
+
+    def _touch(self, key: tuple[Any, ...]) -> None:
+        """Remember the pre-transaction value of a key before mutating it."""
+        if key in self._touched:
+            return
+        table = getattr(self._pool, _TABLE_ATTRS[key[0]])
+        value = table.get(key[1:])
+        if isinstance(value, dict):
+            # Snapshot copies so later in-place updates stay reversible.
+            value = {
+                sub_key: dict(sub_row) if isinstance(sub_row, dict) else sub_row
+                for sub_key, sub_row in value.items()
+            }
+        self._touched[key] = value
+        self._active = True
+
+
+class _FakeCursor:
+    """Cursor-shaped result of one executed statement."""
+
+    def __init__(
+        self,
+        pool: FakePostgresPool,
+        connection: _FakeConnection,
+        rows: list[dict[str, Any]],
+        rowcount: int,
+    ) -> None:
+        self._pool = pool
+        self._connection = connection
+        self._rows = list(rows)
+        self.rowcount = rowcount
+        self.timeout: float = 30.0
+
+    def execute(
+        self, sql: str, params: tuple[Any, ...] = ()
+    ) -> _FakeCursor:
+        return self._pool._execute(self._connection, sql, params, self.timeout)
+
+    def fetchone(self) -> dict[str, Any] | None:
+        return self._rows.pop(0) if self._rows else None
+
+    def fetchall(self) -> list[dict[str, Any]]:
+        rows, self._rows = self._rows, []
+        return rows
+
+
+@contextlib.contextmanager
+def _connection(pool: FakePostgresPool) -> Iterator[_FakeConnection]:
+    """One transaction-backed connection; ``commit``/``rollback`` explicit."""
+    with pool._struct_lock:
+        if pool._closed:
+            raise PoolClosed("fake pool is closed")
+        connection = _FakeConnection(pool)
+    try:
+        yield connection
+    finally:
+        connection._finish()

nl2data_semantic_catalog_postgres/fake_postgres/handlers_audit.py

@@ -0,0 +1,243 @@
+"""Assembly audit-evidence statement handlers for the fake pool.
+
+Writers lock the key slot before checking existence so concurrent writers
+serialize like the real unique indexes.  The bounded trail handlers mirror
+the real SQL's optional-filter and keyset-cursor semantics exactly: an
+unbound equality filter matches every row (the SQL guard is
+``(%s IS NULL OR col = %s)``), and the cursor keyset resumes strictly
+after ``(occurred_at, event_id)``.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+from .driver import UniqueViolation, _as_dt
+from .keys import (
+    _audit_entry_key,
+    _lock_or_fail,
+    _publication_audit_evidence_key,
+)
+
+if TYPE_CHECKING:
+    from .driver import _FakeConnection
+    from .pool import FakePostgresPool
+
+
+def _h_insert_publication_audit_evidence(
+    pool: FakePostgresPool, conn: _FakeConnection, params: tuple[Any, ...], timeout: float
+) -> tuple[list[dict[str, Any]], int]:
+    key = _publication_audit_evidence_key(params[0], params[1], params[2])
+    _lock_or_fail(pool, conn, key, timeout)
+    if key[1:] in pool.publication_audit_evidence:
+        raise UniqueViolation("publication audit evidence already exists")
+    if any(
+        row["scope_namespace"] == params[0]
+        and row["evidence_fingerprint"] == params[3]
+        for row in pool.publication_audit_evidence.values()
+    ):
+        raise UniqueViolation("publication audit evidence fingerprint already exists")
+    conn._touch(key)
+    pool.publication_audit_evidence[key[1:]] = {
+        "scope_namespace": params[0],
+        "bundle_id": params[1],
+        "bundle_fingerprint": params[2],
+        "evidence_fingerprint": params[3],
+        "schema_version": params[4],
+        "envelope": params[5],
+        "created_at": _as_dt(params[6]),
+    }
+    return ([], 1)
+
+
+def _h_read_publication_audit_evidence(
+    pool: FakePostgresPool, conn: _FakeConnection, params: tuple[Any, ...], timeout: float
+) -> tuple[list[dict[str, Any]], int]:
+    row = pool.publication_audit_evidence.get(params)
+    if row is None:
+        return ([], 0)
+    return (
+        [
+            {
+                "evidence_fingerprint": row["evidence_fingerprint"],
+                "envelope": row["envelope"],
+                "schema_version": row["schema_version"],
+            }
+        ],
+        0,
+    )
+
+
+def _h_insert_audit_entry(
+    pool: FakePostgresPool, conn: _FakeConnection, params: tuple[Any, ...], timeout: float
+) -> tuple[list[dict[str, Any]], int]:
+    namespace, event_id = params[0], params[1]
+    key = _audit_entry_key(namespace, event_id)
+    _lock_or_fail(pool, conn, key, timeout)
+    if (namespace, event_id) in pool.audit_entries:
+        return ([], 0)  # ON CONFLICT (scope_namespace, event_id) DO NOTHING
+    conn._touch(key)
+    pool.audit_entries[(namespace, event_id)] = {
+        "scope_namespace": namespace,
+        "event_id": event_id,
+        "event_kind": params[2],
+        "subject_kind": params[3],
+        "subject_reference": params[4],
+        "draft_id": params[5],
+        "draft_revision": params[6],
+        "assertion_id": params[7],
+        "bundle_fingerprint": params[8],
+        "lifecycle_reference": params[9],
+        "entry_fingerprint": params[10],
+        "schema_version": params[11],
+        "envelope": params[12],
+        "occurred_at": _as_dt(params[13]),
+    }
+    return ([], 1)
+
+
+def _h_read_audit_entry(
+    pool: FakePostgresPool, conn: _FakeConnection, params: tuple[Any, ...], timeout: float
+) -> tuple[list[dict[str, Any]], int]:
+    row = pool.audit_entries.get(params)
+    if row is None:
+        return ([], 0)
+    return (
+        [
+            {
+                "entry_fingerprint": row["entry_fingerprint"],
+                "envelope": row["envelope"],
+                "schema_version": row["schema_version"],
+                "occurred_at": row["occurred_at"],
+            }
+        ],
+        0,
+    )
+
+
+def _h_read_publication_audit_entry(
+    pool: FakePostgresPool, conn: _FakeConnection, params: tuple[Any, ...], timeout: float
+) -> tuple[list[dict[str, Any]], int]:
+    namespace, lifecycle_reference = params
+    for (scope, event_id), row in pool.audit_entries.items():
+        if (
+            scope == namespace
+            and row["lifecycle_reference"] == lifecycle_reference
+            and row["event_kind"] == "publication"
+        ):
+            return ([{"event_id": event_id}], 0)
+    return ([], 0)
+
+
+def _h_read_latest_publication_entry(
+    pool: FakePostgresPool, conn: _FakeConnection, params: tuple[Any, ...], timeout: float
+) -> tuple[list[dict[str, Any]], int]:
+    namespace, bundle_fingerprint = params
+    matches = [
+        (row["occurred_at"], event_id)
+        for (scope, event_id), row in pool.audit_entries.items()
+        if (
+            scope == namespace
+            and row["bundle_fingerprint"] == bundle_fingerprint
+            and row["event_kind"] == "publication"
+        )
+    ]
+    if not matches:
+        return ([], 0)
+    matches.sort(reverse=True)
+    return ([{"event_id": matches[0][1]}], 0)
+
+
+def _audit_entry_matches(
+    row: dict[str, Any], event_id: str, params: tuple[Any, ...]
+) -> bool:
+    """Mirror the shared ``count_audit_evidence``/``list_audit_evidence`` WHERE."""
+    (
+        _namespace,
+        draft_id,
+        _draft_id,
+        assertion_id,
+        _assertion_id,
+        bundle_fingerprint,
+        _bundle_fingerprint,
+        lifecycle_reference,
+        _lifecycle_reference,
+        revision_min,
+        _revision_min,
+        revision_max,
+        _revision_max,
+        predecessor_event_id,
+        _predecessor,
+        cursor_at,
+        _cursor_at,
+        cursor_id,
+    ) = params
+    if draft_id is not None and row["draft_id"] != draft_id:
+        return False
+    if assertion_id is not None and row["assertion_id"] != assertion_id:
+        return False
+    if bundle_fingerprint is not None and row["bundle_fingerprint"] != bundle_fingerprint:
+        return False
+    if lifecycle_reference is not None and row["lifecycle_reference"] != lifecycle_reference:
+        return False
+    revision = row["draft_revision"]
+    if revision_min is not None and (revision is None or int(revision) < int(revision_min)):
+        return False
+    if revision_max is not None and (revision is None or int(revision) > int(revision_max)):
+        return False
+    if predecessor_event_id is not None:
+        envelope = json.loads(row["envelope"])
+        predecessors = (
+            (envelope.get("payload") or {}).get("predecessor_event_ids") or []
+        )
+        if predecessor_event_id not in predecessors:
+            return False
+    if cursor_at is not None:
+        position = (row["occurred_at"], event_id)
+        if position <= (_as_dt(cursor_at), cursor_id):
+            return False
+    return True
+
+
+def _h_count_audit_evidence(
+    pool: FakePostgresPool, conn: _FakeConnection, params: tuple[Any, ...], timeout: float
+) -> tuple[list[dict[str, Any]], int]:
+    namespace = params[0]
+    total = sum(
+        1
+        for (scope, event_id), row in pool.audit_entries.items()
+        if scope == namespace and _audit_entry_matches(row, event_id, params)
+    )
+    return ([{"total": total}], 0)
+
+
+def _h_list_audit_evidence(
+    pool: FakePostgresPool, conn: _FakeConnection, params: tuple[Any, ...], timeout: float
+) -> tuple[list[dict[str, Any]], int]:
+    namespace, limit = params[0], int(params[-1])
+    matches = [
+        (
+            row["occurred_at"],
+            event_id,
+            row["entry_fingerprint"],
+            row["envelope"],
+            row["schema_version"],
+        )
+        for (scope, event_id), row in pool.audit_entries.items()
+        if scope == namespace
+        and _audit_entry_matches(row, event_id, params[:-1])
+    ]
+    matches.sort()
+    rows = [
+        {
+            "event_id": event_id,
+            "entry_fingerprint": entry_fingerprint,
+            "envelope": envelope,
+            "schema_version": schema_version,
+            "occurred_at": occurred_at,
+        }
+        for occurred_at, event_id, entry_fingerprint, envelope, schema_version
+        in matches[:limit]
+    ]
+    return (rows, len(rows))