# AI Search Result Reranking

## Objective

Reorder search results by what the user actually meant, without changing what they may see.

A post-retrieval ordering pass over a bounded candidate set, with a deterministic fallback and a record of why the order changed.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Run reranking strictly after the secure search layer has produced its result set. The reranker orders what it is given and must never widen the set or fetch a record on its own.
2. Cap the candidate set to a fixed number of top results and a fixed latency budget. If the pass does not return within that budget, ship the original order rather than making the user wait.
3. Preserve exact-match precedence: identifiers, quoted terms, and exact title matches keep their positions and are excluded from reordering.
4. Keep a per-query record of the original order, the reranked order, and the score or reason for each move, visible to operators so a surprising result can be explained.
5. Candidate retrieval, embedding, and index freshness belong to Semantic Search. This feature owns only the ordering of results already retrieved.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- The reranker must only ever see records the secure search layer already cleared. Passing it raw candidates before filtering turns a ranking feature into a permission leak.
- Reranking an unbounded result set is slow and expensive. Fix a candidate ceiling and a cost ceiling per query, and degrade to the original order past either.
- Moving an exact identifier match off the first position makes the search look broken. Pin exact and quoted matches ahead of the reranked remainder.
- Ranking changes that nobody can explain destroy trust in search. Log inputs and per-result reasons so an operator can reconstruct any specific ordering afterwards.
- A model failure, timeout, or malformed score list must fall back to the deterministic ranking silently. The user sees slightly worse ordering, never an error page.
- Scores that come back for fewer results than were sent, or reference records that were not in the candidate set, must be discarded entirely rather than partially applied.
- Pagination must be computed after reranking, or the second page will repeat or skip records the user already saw.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] The reranker receives only records already authorized by the secure search layer.
- [ ] Every query has a candidate ceiling and a latency budget, past which the original order is returned.
- [ ] Exact identifier, quoted, and exact-title matches retain their leading positions.
- [ ] Original order, final order, and per-result reasons are recorded and inspectable by operators.
- [ ] Model failures and malformed scores fall back to deterministic ranking with no user-visible error.
- [ ] Paging through reranked results never repeats or drops a record.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.