Design a payload-free pcap/RTP ingestion adapter with capture-health evidence

[engkimo]

Problem

VoxBench can ingest normalized RTP packet observations through its library boundary and aggregate RTCP through Asterisk AMI, but the local Asterisk workflow does not yet consume a real pcap or live packet capture. Without capture-health evidence, an apparent sequence gap can be confused with a drop in the observation path itself.

Goal

Design and implement a bounded adapter that converts pcap or live RTP headers into the existing RTP observation contract without retaining packet payloads or sensitive network identifiers.

Design requirements

• Parse only the header fields required for direction, payload type, sequence/extended sequence, RTP timestamp, marker, and arrival time.
• Discard media payload bytes immediately.
• Normalize addresses, ports, SSRCs, call IDs, and channel identifiers into safe aliases or omit them.
• Emit explicit capture-health windows and capture-drop counters.
• Define clock-rate and direction configuration instead of guessing.
• Bound file size, packet count, memory, processing time, and malformed-input behavior.
• Keep aggregate RTCP evidence distinct from packet-level proof.

Acceptance criteria

• Synthetic fixtures cover clean cadence, verified sequence gap, reordering, wraparound, capture drop, truncation, and malformed input.
• A verified gap requires adequate capture health.
• Capture loss produces an unobserved or capture-limited conclusion rather than a network-loss claim.
• No RTP payload or raw endpoint identifiers appear in persisted observations or errors.
• The adapter can feed the existing RtpPacketTapAdapter/observer path without changing core incident semantics.
• Security and library-integration documentation are updated.

Likely areas

• src/voxbench/observability/observer.py
• a new bounded adapter under src/voxbench/telephony/ or src/voxbench/observability/
• docs/library-integration.md
• deterministic packet fixtures and tests

Out of scope

• A full Wireshark replacement.
• Persisting pcap files in the run repository.
• Deep packet inspection of SIP bodies or RTP media.
• Inferring which physical network segment lost a packet.

VoIP, packet-capture, and privacy review are especially welcome.