NOJIRA-timeline-manager-peer-events - #1135
Merged
Merged
Conversation
- bin-timeline-manager: Add design doc for peer_events ClickHouse table (call/conversation address-searchable event log, additive to existing events table)
- bin-timeline-manager: Fix design doc round 1 BLOCKERs — publisher-vs-eventtype conflation and call-manager's multiple incompatible webhook shapes on the same queue (groupcall/recording/confbridge). Replace with explicit (Publisher, EventType) allowlist. Clarify CRM eligibility filter stays contact-manager-private when DeriveEndpoints moves to bin-common-handler.
- bin-timeline-manager: Fix design doc round 2 MAJOR — publisher storage column derivation was unspecified, could silently collapse conversation_message and conversation into the same stored string. Add explicit buildPeerEventRows dispatch code and correct schema comment. Fix round 2 MINORs — name dtmf_received/account_* in exclusion list.
- bin-timeline-manager: Address round 3 MINOR polish (first APPROVE round) — document import paths, clarify PeerEventRow struct is a design-level abstraction, note direction-unset edge case, add explicit test-plan cases (allowlist-miss/malformed-payload/direction-unset), add review history table.
- bin-timeline-manager: Record round 4 APPROVE (second consecutive) in review history table, correct round 2 MINOR count. Design review loop terminated — doc is implementation-ready.
- bin-common-handler: Add shared DeriveEndpoints helper to models/address, promoted from bin-contact-manager's private deriveEndpoints (design doc §6). Single authority for the direction-swap rule so bin-contact-manager and bin-timeline-manager cannot drift.
- bin-contact-manager: Repoint EventCallCreated/EventConversationMessageCreated to the shared commonaddress.DeriveEndpoints helper (bin-common-handler), delete the private deriveEndpoints copy. crmIneligiblePeerTypes/isCRMEligiblePeer stay contact-manager-private (design doc §6). Update regression test to call the shared function.
- bin-timeline-manager: Add peer_events ClickHouse table (migration 000005), PeerEventRow/PeerEventBatchInsert dbhandler, and eligiblePeerEvents (Publisher,EventType) allowlist + buildPeerEventRows projection wired into flushBatch. Additive to the existing events table, no new queue subscription. Covers call-manager's 9 call.WebhookMessage event types and conversation-manager's 6 events (3 message.WebhookMessage + 3 conversation.WebhookMessage). Full unit + integration test coverage per design doc §9 (allowlist-miss, malformed-payload per branch, direction-unset, mixed-batch).
- bin-timeline-manager: Address PR review round 1 findings — give the peer_events insert its own fresh 10s timeout budget instead of reusing the primary events-insert ctx (avoids latency coupling between the two independent writes). Add explicit regression test locking in the events-insert-failure-skips-peer-projection contract.
- bin-timeline-manager: Document round 2 PR review addendum resolving the bin-common-handler admission-rule question (models/address is a pre-existing 10+-service package, DeriveEndpoints is a function addition not a new package).
pchero
added a commit
that referenced
this pull request
Jul 24, 2026
Add a new read-only API path over bin-timeline-manager's existing peer_events ClickHouse table (ingestion was added and merged in a prior session, PR #1135; the read path was explicitly scoped out at the time). Lets square-admin/square-talk query raw peer/local address activity for a contact's registered addresses (contact_id) or a single peer address (peer_type + peer_target). Returns rows as-is, including internal-resource noise (agent/AI/conference/SIP legs) that contact_interactions deliberately excludes -- by explicit product decision, no server-side eligibility filter is applied; clients are responsible for any presentation-layer filtering. contact_interactions and its algorithm are left completely untouched; this is purely additive. Post-approval, peer/local were redesigned from flat peer_type/peer_target strings to full commonaddress.Address objects (matching contact_interactions' own Peer/Local shape), stored as new JSON columns in peer_events (migration 000006) alongside the existing internal-only flat search columns. The external peer_type/peer_target query params are unchanged; only the response shape and internal request/filter plumbing were unified onto commonaddress.Address end to end. Went through a 5-round adversarial PR review loop (2 consecutive clean APPROVEs) that caught and fixed 3 documentation-accuracy defects and 1 test-coverage gap; no BLOCKER-level code defects were found. Full history recorded in docs/plans/2026-07-24-peer-events-read-api-design.md sections 14-21. - bin-timeline-manager: models/peerevent (new package: PeerEvent with Peer/Local as commonaddress.Address, PeerEventListRequest/Response) - bin-timeline-manager: dbhandler.PeerEventList (ClickHouse OR-expansion query over peer_type+peer_target pairs derived from commonaddress.Address, added to the DBHandler interface); migration 000006 adds peer/local JSON columns alongside the existing internal-only flat search columns - bin-timeline-manager: pkg/peereventhandler (new package, business logic + pagination, commonaddress.Address-based interface matching eventhandler's pattern) - bin-timeline-manager: listenhandler GET /v1/peer-events route + DTOs - bin-common-handler: requesthandler.TimelineV1PeerEventList (GET, mirrors TimelineV1AnalysisList's query-authority + body-filter shape) - bin-openapi-manager: new TimelineManagerPeerEvent / TimelineManagerPeerEventListResponse schemas, contact_peer_events and service_agents/contact_peer_events path specs - bin-api-manager: servicehandler.PeerEventList / ServiceAgentPeerEventList (resolvePeerAddresses: contact_id resolves via existing contactGet + Contact.Addresses, or a single peer_type+peer_target passthrough constructed into commonaddress.Address; anti-enumeration ErrNotFound on cross-tenant contact_id) - bin-api-manager: GET /contact_peer_events and GET /service_agents/contact_peer_events server handlers - bin-api-manager: RST docs (contact_peer_event_overview, contact_peer_event_struct) + rebuilt docsdev/build HTML - docs: design doc sections 14-21 record the post-approval redesign and the full 5-round PR review loop disposition
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Add a new peer_events ClickHouse table to bin-timeline-manager: an address-searchable event log scoped to call-manager and conversation-manager events, additive to the existing events table. Design-first workflow completed (4 rounds, 2 consecutive APPROVE) — see the design doc for full round-by-round history.