# KORA Studio Fixture Schema Reference

## Purpose

This doc describes static fixture shapes for future KORA Studio UI work. The fixtures are planning samples only and do not mean KORA Studio is implemented.

## Common Fields

- `fixture_id`: stable identifier for the sample artifact.
- `fixture_type`: sample category, such as `local_validation_summary`, `dashboard_counters`, or `project_chat_session`.
- `mode`: validation or UI mode represented by the fixture.
- `provider`: local validation or runtime label represented by the fixture.
- `model`: model label represented by the fixture.
- `privacy_class`: fixture privacy class; public Studio fixtures should use `synthetic`.
- `claim_boundary`: explicit boundary text for what the fixture does and does not show.

## Counter Fields

- `total_requests`: number of requests or tasks represented by the sample.
- `baseline_model_calls`: model-call events recorded by the direct baseline path.
- `kora_model_calls`: model-call events recorded by the KORA-controlled path.
- `avoided_model_calls`: baseline model calls minus KORA model calls.
- `avoided_model_call_rate`: avoided model calls divided by baseline model calls when available.
- `deterministic_routes`: requests handled by deterministic or fast local paths.
- `model_escalations`: requests escalated to the selected model-call path.
- `validation_pass_count`: validation checks that passed.
- `validation_fail_count`: validation checks that failed.
- `error_count`: runtime or validation errors counted by the sample.
- `fallback_count`: requests that fell back because a route was unsupported or unresolved.

## Project Chat Fields

- `project`: project metadata, including project id, name, mode, selected model, runtime, and privacy class.
- `messages`: synthetic user and assistant messages for a future project chat UI mock.
- `execution_traces`: route-level trace objects connected to messages.

## Report Viewer Fields

- `report_title`: display title for the report.
- `report_path`: local sample path used for UI planning.
- `report_fixture_path`: public fixture metadata path used by the local preview scaffold.
- `sections`: expected report sections for navigation.
- `counters`: aggregate counter object extracted from a report or companion JSON.
- `boundary_warnings`: warnings the UI should keep visible near report content.
- `arbitrary_local_file_scan_enabled`: whether the viewer scans arbitrary local files; public preview fixtures should keep this false.
- `upload_enabled`: whether report upload is connected; public preview fixtures should keep this false.
- `generated_report_commit_enabled`: whether generated report commit behavior is connected; public preview fixtures should keep this false.

## Execution Viewer Event Fields

- `run_id`: local fixture run identifier.
- `request_id`: local fixture request identifier.
- `stage_id`: stable stage identifier for replay.
- `stage_name`: display name for the stage.
- `route_class`: route represented by the stage, such as input, deterministic code, structured lookup, validation, local model, or summary.
- `status`: fixture status such as completed or skipped.
- `started_at`: fixture timestamp for UI ordering.
- `completed_at`: fixture timestamp for UI ordering.
- `latency_ms`: fixture latency value when represented.
- `model_called`: whether the fixture stage represents a model call.
- `deterministic_route_used`: whether deterministic routing was used.
- `structured_lookup_used`: whether structured lookup was used.
- `validation_result`: validation result, such as pass or not_applicable.
- `adapter_name`: fixture adapter label.
- `adapter_mode`: fixture adapter mode.
- `provider_calls_enabled`: provider-call state represented by the fixture; public fixtures should keep this false.
- `cloud_sync_enabled`: cloud-sync state represented by the fixture; public fixtures should keep this false.
- `counters_snapshot`: stage-level counter snapshot.
- `error_code`: fixture error code if one is represented.
- `error_message`: fixture error message if one is represented.

## Standard Mode vs KORA Boost Comparison Fields

- `comparison_input`: synthetic fixture input shared by both modes.
- `modes`: mode-level fixture objects for Standard Mode and KORA Boost.
- `model_call_count`: model-call count represented by one mode in the fixture.
- `deterministic_route_used`: whether the mode used deterministic routing in the fixture.
- `structured_lookup_used`: whether the mode used structured lookup in the fixture.
- `metrics`: aggregate fixture counters for the comparison.
- `metric_cards`: display-ready metric card objects when generated by code.
- `cost_claim_enabled`: whether the fixture enables cost claims; public comparison fixtures should keep this false.
- `energy_claim_enabled`: whether the fixture enables energy claims; public comparison fixtures should keep this false.

## Local Harness Request Fields

- `request_id`: stable local harness request identifier.
- `input_text`: synthetic request text.
- `task_family`: deterministic task family represented by the request.
- `expected_route_class`: expected route class, such as deterministic code, policy, structured lookup, or model-needed boundary.
- `expected_validation_result`: expected validation result, such as pass or not_applicable.
- `expected_model_needed`: whether the sample should stop at a model-needed boundary.
- `claim_boundary`: explicit boundary text for what the request set does and does not show.
- `expected_checks`: local deterministic checks expected for the request.
- `provider_calls_enabled`: provider-call state; public harness samples should keep this false.
- `cloud_sync_enabled`: cloud-sync state; public harness samples should keep this false.
- `model_execution_connected`: model-execution state; public harness samples should keep this false.

## Claim-Safe Display Rules

- show measured counters only
- do not convert avoided model calls into cost savings
- do not show energy savings
- do not imply production validation
- label local/no-network validation clearly
- label execution viewer events as fixture/mock data unless they are generated by a future approved local harness
- keep Standard Mode vs KORA Boost comparison metrics as fixture/mock counters, not production or billing evidence
