# OSHUN Search Ranking Strategy

Status: Active  
Owner: OSHUN BFF  
Last Updated: March 22, 2026

## Purpose

Define deterministic cross-domain ranking behavior for `GET /search` across
Tara, Arete, Veritas, Nyx, and Nisaba.

This document defines the V1 target ranking model. Implementation references may
still reflect the older four-domain shell until the corresponding V1 search and
contract tasks are complete.

## Candidate Inputs

Each candidate contributes:

- `domain`: `tara | arete | veritas | nyx | nisaba`
- `kind`: `continue | highlight`
- `title`
- `summary`

Candidates are sourced from existing domain adapters:

- Continue items (resume context)
- Highlight/recommended items (discover context)

## Scoring Formula

Final score:

```text
score = lexical + kindBoost + domainIntentBoost
```

Where:

- `lexical`:
  - exact query phrase in title: `+40`
  - exact query phrase in summary: `+24`
  - per-token title match: `+8`
  - per-token summary match: `+3`
- `kindBoost`:
  - `continue`: `+14`
  - `highlight`: `+7`
- `domainIntentBoost`:
  - if query explicitly includes a domain name and candidate matches: `+10`
  - if query includes a different domain name: `-4`

For empty queries, lexical baseline is `+1` so curated defaults still rank.

## Filtering Rules

- Results with score `<= 0` are dropped.
- Optional domain filter (`domain=all|tara|arete|veritas|nyx|nisaba`) is applied
  before ranking.

## Ordering Rules

Tie-break order:

1. Higher score
2. Domain order: `tara`, `arete`, `veritas`, `nyx`, `nisaba`
3. Lexicographic title

## Implementation References

- Strategy module: `apps/oshun/bff/src/search/ranking.ts`
- Search endpoint: `apps/oshun/bff/src/routes/search.ts`
- Ranking tests: `apps/oshun/bff/src/__tests__/search-ranking.test.ts`
