Eve library

OSHUN Search Ranking Strategy

Spec

Revision 1

On this page

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