# OSHUN Notification Deduplication Strategy

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.
