Stage 209: handlers.list_audit_logs entity_id filter

infra/api/handlers.py

@@ -1148,12 +1148,66 @@ def export_tenant(svc: OrgStateService, tenant_id: str) -> dict:
 def list_audit_logs(svc: OrgStateService, *,
                     actor: Optional[str] = None,
                     action: Optional[str] = None,
+                    entity_id: Optional[str] = None,
                     tenant_id: Optional[str] = None,
                     limit: int = 100,
                     offset: int = 0) -> dict:
-    rows = svc.audit.list(actor=actor, action=action, tenant_id=tenant_id,
-                           limit=limit, offset=offset)
-    return {"audit_logs": rows, "limit": limit, "offset": offset}
+    """Stage 209 — ``entity_id`` filter matches audit rows whose
+    payload references the entity. Currently used by
+    bulk_update_decisions (which lists ``entity_ids`` per Stage 206)
+    and decision-status events (whose payload carries a single
+    ``entity_id``). Other action types are unaffected.
+
+    Implementation: post-filter on the JSON payload. We over-fetch
+    (10× the requested limit) from the DB and trim after filtering
+    so the typical "find a few touches on widget_42" query
+    returns the right rows without a schema change. For very
+    large tenants with mostly-irrelevant rows we may return
+    fewer than ``limit`` even when more matches exist past the
+    over-fetch window; a future stage can add a denormalized
+    entity_id index column.
+    """
+    if entity_id is None:
+        rows = svc.audit.list(
+            actor=actor, action=action, tenant_id=tenant_id,
+            limit=limit, offset=offset,
+        )
+        return {"audit_logs": rows, "limit": limit, "offset": offset}
+
+    # Entity filter path — over-fetch + post-filter.
+    raw = svc.audit.list(
+        actor=actor, action=action, tenant_id=tenant_id,
+        limit=limit * 10, offset=offset,
+    )
+    matched = []
+    for r in raw:
+        if _audit_row_mentions_entity(r, entity_id):
+            matched.append(r)
+            if len(matched) >= limit:
+                break
+    return {"audit_logs": matched, "limit": limit, "offset": offset}
+
+
+def _audit_row_mentions_entity(row: dict, entity_id: str) -> bool:
+    """Return True iff the row's payload references the entity.
+
+    Two shapes we currently know:
+    - bulk_update_decisions (Stage 206): payload.entity_ids is a list.
+    - decision-side actions: payload.entity_id is a single string.
+    Falls through to False on unknown shapes — adding new action
+    types is opt-in via this matcher, NOT a leaky default that
+    would silently include unrelated rows.
+    """
+    payload = row.get("payload") or {}
+    if not isinstance(payload, dict):
+        return False
+    ids = payload.get("entity_ids")
+    if isinstance(ids, list) and entity_id in ids:
+        return True
+    single = payload.get("entity_id")
+    if isinstance(single, str) and single == entity_id:
+        return True
+    return False
 
 
 def run_from_stored(svc: OrgStateService, tenant_id: str,