fix(audit): honest cap + cursor for /v1/audit/public and /v1/audit/{id}

[hizrianraz]

Summary

• /v1/audit/public previously silently truncated ?limit=N to 100 — a contract bug for AI-native callers passing higher limits and trusting the response is complete (Memory feat(users): add recent_events + chain_meta to /v1/users/{handle}/dashboard #14). Now honestly capped at 500 with 422 above.
• /v1/audit/{agent_id} had the same family of bug in inverse: no limit parameter at all (returned the entire chain unbounded). Now optionally cappable; omitting limit preserves backward-compat full-chain behavior for ainfera-verify.
• Both endpoints gain a since_seq cursor for bandwidth-cheap live-feed polling — the homepage widget should migrate to this rather than re-fetching the full window every 12s (fast-follow web PR).

Why

Surfaced by the 2026-05-16 E2E HALT diagnosis. The recency-rank pre-flight assertion ("≥5 distinct agents in last 200 events") was failing because:

1. The 100-cap meant ?limit=200 returned 100 events
2. Any chatty agent (varda) monopolizes the slot ranking
3. Time-window probes are the right shape for fleet liveness — not recency-rank

The silent cap masked that deeper category error. Fixing the contract honesty is a prereq for the companion E2E script swap (G4 → /v1/heartbeat/latest, C5 → per-agent time-window).

Changes

• ainfera_api/routers/audit.py — Query(...) params on both endpoints; since_seq cursor; unchanged /annex-iv (separate design question)
• tests/integration/test_audit_public_cap.py — 8 integration tests covering: default works, cap honored at 500, 422 above, 422 at 0, cursor returns ascending filtered, backward-compat full-chain mode

Test plan

• make typecheck (mypy --strict, clean)
• make lint (ruff, clean)
• make test (387 unit tests pass)
• RUN_INTEGRATION=1 make test-integration (53 integration tests pass, includes 8 new)
• CI green
• Post-merge: curl https://api.ainfera.ai/v1/audit/public?limit=600 → 422
• Post-merge: curl https://api.ainfera.ai/v1/audit/public?since_seq=1&limit=50 returns events with seq > 1 ascending

Out of scope (separate)

• scripts/e2e-agent-check.sh — companion E2E script lives in parent ainfera-ai dir (not a git repo). G4 swapped to heartbeat probe, C5 to per-agent time-window, G7/G8 added for cap honesty
• /annex-iv pagination — Annex IV exports are meant to be full bundles
• Homepage widget cursor migration — fast-follow web PR
• AIN-129 PEM URL-encoding (per founder spec)

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes public and per-agent audit API query semantics (validation, ordering, and optional limiting), which may affect existing clients relying on previous silent truncation or ordering.

Overview
Audit feed endpoints now have explicit, honest pagination controls. /v1/audit/public switches from silently truncating limits to enforcing limit via Query validation (default 20, max 500, 422 on out-of-range), and adds a since_seq cursor mode that returns seq > since_seq in ascending order.

Per-agent audit chain adds optional bounding and cursoring while keeping backward compatibility. /v1/audit/{agent_id} now accepts optional limit (max 500; omitted still returns the full chain) and since_seq filtering, with new integration tests covering caps and cursor behavior for both endpoints.

^{Reviewed by Cursor Bugbot for commit 78def5f. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is ON. A cloud agent has been kicked off to fix the reported issue.}

^{Reviewed by Cursor Bugbot for commit 78def5f. Configure here.}

[cursor]

Public feed cursor uses per-agent seq as global cursor

High Severity

The since_seq cursor on /v1/audit/public filters by AuditEventORM.seq > since_seq across all agents, but seq is a per-agent counter (starts at 0 for each agent, unique constraint is (agent_id, seq)). This makes the cursor fundamentally broken for cross-agent polling: a caller passing since_seq=100 will silently miss every event from any agent with fewer than 101 events. The integration test only passes because both test agents produce the same number of events, making their seq ranges identical.

 

^{Reviewed by Cursor Bugbot for commit 78def5f. Configure here.}