spb/search-box Public

1<!--2Search-box.ai3Author: Simon-Pierre Boucher4Contact: contact@spboucher.ai5File: docs/research-state.md6Description: The durable ResearchState model.7-->89# ResearchState1011All research state lives in PostgreSQL (`packages/db/migrations/001_init.sql`), not in the12model's context window. Sessions are resumable and replayable.1314## Entities1516- **Session** — question, status (`pending → running → synthesizing → completed|failed`),17  objectives, budgets, final answer.18- **Source** — every URL seen. `found → fetched|failed`. Fetched sources store up to 120k19  chars of markdown. `citation_index` is assigned mechanically at synthesis.20- **Evidence** — verbatim quote from a source, attached to a claim with a stance21  (`supports | contradicts | context`). Quotes are soft-verified against stored content;22  unverified quotes get flagged in `note`.23- **Claim** — falsifiable statement with status (`exploring | supported | contradicted |24  uncertain`) and confidence (0..1 probability).25- **Contradiction** — first-class record of credible disagreement, referencing the26  conflicting evidence ids.2728## Provenance chain2930`answer sentence → [n] marker → citation_index → source → evidence quotes → claims`3132Citation indices are derived mechanically from state (sources ordered by first evidence33use). The synthesis model never invents numbering.3435## Events3637Every mutation appends exactly one event row (`research_events`, monotonic `seq`).38The event log is the replay/debug record: replaying a session's events from seq 039reconstructs everything the user saw live.40