SuperBizAgent-java/openspec/specs/single-react-chat-application-usecase/spec.md

single-react-chat-application-usecase Specification

Purpose

TBD - created by archiving change single-react-chat-application-usecase. Update Purpose after archive.

Requirements

Requirement: Application-owned session and Run lifecycle

The Chat Application Use Case SHALL resolve or generate the session ID, create exactly one RunContext, persist one matching Diagnosis Run, and propagate the same session ID, run ID, original Query, cancellation, budget, and terminal outcome through routing and the selected executor.

Scenario: Existing session request

• WHEN an internal request supplies a valid session ID
• THEN the use case preserves it, generates one run ID, and returns/persists the same identifiers

Scenario: New session request

• WHEN an internal request omits the session ID
• THEN the use case generates one valid session ID and uses it for all Run operations

Requirement: Minimal isolated Intent Router

The Router SHALL execute a direct no-Tool, no-memory, no-ReAct ChatModel call whose input contains only the unchanged Query, optional last intent, and optional last user Query. It SHALL accept only SYSTEM_CHAT, KNOWLEDGE_QUERY, or DIAGNOSIS.

Scenario: Three valid routes

• WHEN the model returns each supported enum in the strict output schema
• THEN the use case dispatches to exactly the corresponding fixed executor

Scenario: New topic overrides history

• WHEN the current Query identifies a new topic while prior routing context exists
• THEN the model input still preserves the original current Query and prior fields are only optional context

Requirement: Router technical retry fails closed

The Router SHALL use HarnessRetryPolicies.intentRouter() and SHALL retry timeout, transport, or invalid output at most once with identical input. A second failure MUST produce ROUTING_UNAVAILABLE and MUST NOT dispatch Diagnosis.

Scenario: Invalid output then valid route

• WHEN the first output is not a supported enum and the second output is valid
• THEN exactly two attempts use the same input and the valid route is executed

Scenario: Two invalid outputs

• WHEN both permitted attempts return invalid output
• THEN the Run ends FAILED and no intent executor is called

Requirement: Fixed isolated executors

The Application Use Case SHALL map SYSTEM_CHAT to one no-Tool model response, KNOWLEDGE_QUERY to exactly one lookup-knowledge invocation plus one bounded answer model call, and DIAGNOSIS to the single Diagnosis Agent followed by the Diagnosis Release boundary. Executors MUST NOT call one another or rewrite the Query. Information saturation and budget termination in Diagnosis SHALL be converted to safe content by Diagnosis Release, not by ChatApplicationUseCase.

Scenario: System Chat

• WHEN intent is SYSTEM_CHAT
• THEN no evidence Tool, Diagnosis Agent, EvidenceGuard, or SemanticGuard is invoked

Scenario: Knowledge Query

• WHEN intent is KNOWLEDGE_QUERY
• THEN only lookup_knowledge is invoked once and query_logs/query_mysql/Diagnosis ReAct are unavailable

Scenario: Diagnosis succeeds with a conclusion

• WHEN intent is DIAGNOSIS and the Draft passes the release guards
• THEN the original Query and bounded PreviousTurn enter DiagnosisAgentUseCase and the Draft publishes only after DiagnosisReleaseUseCase

Scenario: Diagnosis stops without a conclusion

• WHEN Diagnosis collection is saturated, required context is missing, or a handled budget limit is reached
• THEN DiagnosisReleaseUseCase returns bounded Fallback content and ChatApplicationUseCase only persists and transports that decision

Requirement: Knowledge references are physically validated

The Knowledge executor SHALL accept only a bounded READY RAG projection, SHALL validate every model answer item against the exact direct invocation ID and returned document ID set, and SHALL remove Tool Call IDs from public content.

Scenario: Supported knowledge answer

• WHEN answer items reference the exact lookup call and only returned documents
• THEN public content contains answer text, stable document references, and limitations without Tool Call IDs

Scenario: Fabricated knowledge reference

• WHEN the model returns another call ID or an unknown document ID
• THEN the executor fails closed and no knowledge answer is published

Scenario: No knowledge evidence

• WHEN lookup returns READY NO_EVIDENCE
• THEN the executor returns a fixed bounded no-evidence answer without calling the answer model

Requirement: Safe bounded PreviousTurn

The system SHALL load PreviousTurn only from the same Session's most recent Run with intent=DIAGNOSIS, release_outcome=SUCCESS, and non-null valid published_result. It SHALL deterministically bound fields and source documents without model summarization.

Scenario: Last safe Diagnosis exists

• WHEN a qualifying Run contains valid PublishedResult JSON
• THEN the next Diagnosis receives its bounded query, conclusion, scope, limitations, and RAG document metadata

Scenario: Last Run is fallback failed or cancelled

• WHEN newer Runs are not qualifying safe Diagnosis successes
• THEN they cannot become PreviousTurn and the query returns the most recent qualifying record or null

Scenario: Published result is corrupt

• WHEN stored JSON is invalid or required safe fields are blank
• THEN PreviousTurn is null and no raw stored value reaches a model

Requirement: Diagnosis Run persistence contract

The diagnosis_run schema SHALL add nullable intent, release_outcome, and JSON published_result, and the JPA entity/repository/store SHALL write and query them consistently. PublishedResult MUST NOT contain Tool IDs, raw evidence, full Draft, or SemanticGuard reasons.

Scenario: Successful Diagnosis completion

• WHEN a Diagnosis report with non-null conclusion is safely released
• THEN the Run stores intent DIAGNOSIS, release outcome SUCCESS, safe public answer, bounded PublishedResult, duration and budget usage

Scenario: Fallback completion

• WHEN release returns SafeFallback
• THEN the Run status is SUCCESS, release outcome is FALLBACK, and published_result is null

Scenario: Failure or cancellation

• WHEN routing/execution fails or the client cancels the Run
• THEN the Run stores exactly one FAILED or CANCELLED release outcome and no PublishedResult

Requirement: Protocol-neutral progress and cancellation

The use case SHALL notify a protocol-neutral observer after the Run is persisted, expose only session/run identifiers and client-disconnect cancellation, and emit only fixed safe application status codes.

Scenario: Observer start and status

• WHEN internal execution begins
• THEN observer start occurs once before routing status and contains the persisted session/run identifiers

Scenario: Client disconnect control

• WHEN the observer invokes client-disconnect cancellation
• THEN the same RunContext is cancelled and late executor results cannot complete successfully

Requirement: Stage-six-A public isolation

Stage 6A SHALL NOT modify or switch public Chat Controller endpoints, SSE contracts, frontend consumers, or legacy ChatService behavior.

Scenario: Internal-only delivery

• WHEN stage 6A changes are inspected
• THEN Controller/frontend/public endpoint behavior has zero diff and stage 6B can consume the completed use case without rewriting it

Requirement: Handled Diagnosis budget termination SHALL remain a Fallback release

When Diagnosis Release has converted a recognized budget termination and existing safe progress into a Fallback, ChatApplicationUseCase SHALL persist that result exactly once without reclassifying it as INTERNAL_FAILURE, invoking another model, or rebuilding business fallback content. The internal Run lifecycle MAY retain BUDGET_EXHAUSTED, while the persisted public release outcome SHALL be FALLBACK and no PublishedResult SHALL be stored.

Scenario: Tool budget ends after finite checks

• WHEN Diagnosis reaches a hard Tool budget after at least one canonical safe observation and Release creates an insufficient-evidence fallback
• THEN the Run persists status SUCCESS, release outcome FALLBACK, safe content and actual budget usage, and the SSE sends content followed by done

Scenario: Budget ends without safe publishable progress

• WHEN budget termination occurs before Diagnosis Release can form a safe bounded result
• THEN the existing failure path remains fail closed and does not fabricate observed facts