Journey: Sophia grounded answer

Journey flow#

Generated from the authored steps below — click a node to jump to that section.

Sophia now has a shipped customer room at /sophia, a live Nisaba-backed answer route, explicit grounded/partial/ungrounded/abstained states, per-claim labels, citation locators, Library saves, and browser return continuity. The scope is narrower than the platform architecture: this route searches the current Nisaba corpus and does not implement tenant source sets, freshness, retraction, contradiction, or high-stakes review loops.

Personas#

• Signed-in questioner — asks up to 600 characters in the dedicated Sophia room and expects either cited evidence or an honest refusal.
• Evidence reader — inspects witness kind/weight and retrieved/synthesized claim attribution before following a passage into Nisaba.
• Returning researcher — comes back from a citation or reload and expects the last answer to remain available in the current browser session.
• Library user — saves the answer snapshot and witness trail for another device/context under the same account.

Pre-conditions#

• The customer can reach /sophia; the form posts through the BFF origin/CSRF boundary to POST /v1/sophia/answer.
• app.domainAdapters.nisaba.searchLibrary can search the in-process/public Nisaba corpus. This is the only source set used by the customer answer route.
• Optional abstractive synthesis may be configured. The deterministic extractive composer is always available as the fallback.
• Authenticated Library saved-items routes are available for the Save action.

Steps#

1. Ask in the dedicated room#

SophiaAskForm requires non-whitespace input, disables submit while pending, keeps the query visible, and sends { q } to /v1/sophia/answer. Non-OK and network failures render distinct recoverable alerts without replacing the last valid answer with fabricated content.

Search has a related but separate entry: a focused result preview exposes its grounded-evidence status and “Compare with OSHUN” handoff. Search does not itself call the Sophia answer route.

2. Retrieve and compose the answer envelope#

The BFF searches Nisaba for up to six query-relevant records and maps them to citations with id, title, kind, summary, citation label, and a kind-based weight. It returns answer, confidence, citations, claims, citationMap, groundingState, abstained, and a confidence meter.

Default composition quotes the retrieved summaries, emits one retrieved claim per witness, and never asserts beyond those sources. Three or more citations produce grounded; one or two produce partial. No hits produce an ungrounded abstention, while empty input at the API layer produces abstained. When optional LLM synthesis fails or yields unusable claim links, the route fails soft to extractive output.

3. Read grounding, witnesses, and claims#

The customer card displays grounding state, confidence, citation count, answer, witness title/summary/kind/weight, and each claim's retrieved | synthesized | model-only label plus citation ids. The server defensively removes dangling claim ids and never emits a usable model-only claim.

The BFF's richer meter (fill, credibility factors, abstention explainer) is not included in SophiaAskForm's response interface and is not rendered. The visible status line is therefore a summary, not the full returned meter.

4. Follow a passage citation into Nisaba#

Passage citation ids are converted into /domains/nisaba?origin=sophia&path=/library/passage/<id>?locator=<excerpt>. The Nisaba reader asserts the exact passage id, matches and highlights the locator text, and renders the reading frame. Before leaving, Sophia stores its scroll position; Browser Back restores the session-stored answer and returns near that position without refetching.

5. Save the answer snapshot#

Save maps the answer to a nisaba / assistant-excerpt Library item containing the answer text, witness titles, grounding/trust state, and a notebook-shaped resume path. It writes the authenticated saved-items BFF and toggles the common Library save telemetry. Browser coverage clears local Library cache in a second context and proves the saved metadata/witness trail rehydrates there.

The test does not open that generated /workspace/notebook/<answer-id> resume path, so a durable editable notebook representation is not proven.

Post-conditions#

• Every non-abstaining emitted claim has at least one citation id present in the answer's citation list; no model-only or dangling claim is accepted.
• No-hit and empty-query API branches decline rather than inventing sources.
• The last valid answer survives reload in sessionStorage, and citation return restores the answer and approximate scroll position.
• A saved answer snapshot and witness trail are readable from the BFF in a cache-free second context.

Failure modes#

• Nisaba search unavailable/no hits — retrieval becomes an honest no-citation abstention rather than a 500 or uncited prose.
• Synthesizer failure/timeout — falls back to deterministic extractive composition.
• Dangling/model-only synthesis — invalid citation ids are filtered; claimless output abstains.
• Customer route outage — non-2xx and network errors preserve the query and expose retryable alert copy.
• Source-scope overclaim — the answer route does not take tenant/source-set identity and searches Nisaba only.
• Freshness/retraction overclaim — Nisaba results carry no retraction flag; retracted-source is a reserved state that this route never produces.
• Meter invisibility — API consumers receive credibility detail, but the customer card does not render it.
• Saved resume path — saved-item rehydration is covered; opening the synthetic notebook destination is not.

E2E coverage#

• apps/oshun/web/e2e/sophia-answer-bff.spec.ts proves the live grounded, partial, no-hit, and empty-query envelopes, meter, query aliases, and no model-only/dangling claims.
• apps/oshun/web/e2e/sophia-grounded-answer-page.spec.ts drives form states, live answer branches, session restore, citation locator handoff/Back, BFF save metadata, cache-free second-context Library hydration, and outage alerts.
• apps/oshun/web/e2e/assistant-grounding-state.spec.ts covers the adjacent assistant grounding-state presentation, not the Sophia route's retrieval engine.
• Coverage depth: deep for the current Nisaba-backed answer envelope and page. Tenant/freshness/retraction/review loops and saved resume remain open.

Per-view files touched#

• customer/02-home-discovery/search.md — result preview grounding entry.
• customer/07-nisaba/nisaba.md — citation destination and locator highlight.
• customer/02-home-discovery/library.md — saved answer snapshot and second-context read-back.
• shell/04-auth-session.md — protected customer page versus public BFF read semantics.

Cross-references#

• search-explore-deep-read-library-save.md — Search preview and shared Library contract.
• citation-drift-resolution.md — separate citation lifecycle after source movement.
• nisaba-scholarly-read.md — deeper reading tools after the locator handoff.
• Sources: apps/oshun/web/src/app/sophia/SophiaAskForm.tsx, apps/oshun/bff/src/sophia/answer-composer.ts, and the Sophia block in apps/oshun/bff/src/routes/domain-stubs.ts.

Open questions#

• How should tenant/source-set identity enter this route without leaking across scopes?
• Which source metadata enables honest freshness, retirement/retraction, and credibility-factor rendering?
• Should the customer page render the returned confidence meter and abstention explainer?
• Should Save create a real notebook/excerpt artifact whose resume destination is browser-proven, rather than only saved-item metadata?
• Which questions require a high-stakes fact-check/review gate before answer presentation?