SuperBizAgent-java/openspec/changes/archive/2026-07-17-chat-diagnosis-stategraph-chatservice-cutover/specs/session-run-trace-isolation/spec.md

ADDED Requirements

Requirement: StateGraph Chat runs SHALL persist a compact orchestration trace

Each successful new StateGraph complex Chat run SHALL persist a non-empty compact orchestration summary derived from its bounded Graph events in diagnosis_run.orchestration_trace.

Scenario: Graph reaches Composer

• WHEN a complex Chat Graph terminates through Composer with a safe answer
• THEN the current DiagnosisRun SHALL store version, transitions, final node, termination reason, degraded flag, and evidence retry count
• AND the summary SHALL be derived from the current Run's actual orchestration events

Scenario: Graph reaches handled Fallback

• WHEN a complex Chat Graph terminates through deterministic Fallback with a safe answer
• THEN the current DiagnosisRun SHALL store a non-empty orchestration trace with degraded=true
• AND the Run status SHALL be SUCCESS

Scenario: Unhandled execution fails after events exist

• WHEN an unhandled failure occurs after one or more real Graph events are available
• THEN the service SHALL best-effort persist a partial orchestration summary for the current failed run
• AND it SHALL NOT add a node or transition that did not occur

Scenario: Orchestration trace content is inspected

• WHEN orchestration trace JSON is serialized
• THEN it SHALL NOT include Prompt text, model reasoning, raw tool output, raw Executor output, or Graph State snapshots
• AND it SHALL NOT contain data owned by another run

Requirement: Trace API SHALL expose orchestration trace only on the run object

The Trace API SHALL parse the current DiagnosisRun orchestration JSON and expose it only as run.orchestrationTrace.

Scenario: Exact StateGraph run trace is queried

• WHEN a caller queries a successful new StateGraph Chat run
• THEN run.orchestrationTrace SHALL be a non-empty parsed JSON object
• AND the response top level and compatibility session projection SHALL NOT duplicate the field
• AND no raw orchestration trace field SHALL be added

Scenario: Historical or non-StateGraph run is queried

• WHEN the selected DiagnosisRun has null orchestration trace
• THEN run.orchestrationTrace MAY be null
• AND the service SHALL NOT synthesize historical events or read another run's trace

Requirement: Orchestration trace migration SHALL be additive and nullable

The database migration SHALL add only one nullable JSON column named orchestration_trace to diagnosis_run for this change.

Scenario: Migration is applied

• WHEN Flyway applies the stage 3 migration
• THEN existing DiagnosisRun rows SHALL remain valid without backfill
• AND no other table or column SHALL be changed by the stage 3 schema migration