Eve library

OSHUN Notification Deduplication Strategy

Runbook

Revision 1

On this page

Status: Active
Owner: OSHUN BFF

Purpose#

Prevent repeated, semantically equivalent notification events from cluttering the unified OSHUN notifications feed when multiple domain systems surface the same underlying event.

Scope#

Applied in apps/oshun/bff/src/routes/notifications.ts after:

  1. authentication and scope checks
  2. per-domain preference filtering
  3. inbox/domain query filtering

Deduplication then runs before pagination.

Fingerprint Strategy#

Each candidate notification is normalized into a cross-domain event key:

  • normalized(title):
    • lowercase
    • punctuation stripped
    • whitespace collapsed
  • normalized(body):
    • same normalization rules
  • time bucket:
    • 2-hour bucket from timestamp

Key shape:

v1|<normalized-title>|<normalized-body>|<two-hour-bucket>

Cross-Domain Dedup Rule#

  • If a fingerprint group contains items from only one domain:
    • keep all items (no dedup collapse)
  • If a fingerprint group contains items from multiple domains:
    • select exactly one canonical item using winner rules

Winner Selection Rules#

Rank candidates in this order:

  1. priority: high beats normal
  2. read: unread beats read
  3. timestamp: newer beats older
  4. tie-breaker: lexicographically smaller id

This guarantees deterministic output for identical inputs.

Notes#

  • This strategy targets feed ergonomics and reduces duplicate user-facing events.
  • It is intentionally conservative: same-domain duplicates are preserved to avoid suppressing potentially distinct events from a single domain.