Scenario Run Index Surface¶

Status: Candidate post-v1 Core-owned structured surface consolidated in v1.1.0
Scope: scenario run indexing from simulation JSON reports
Applies to: OrbitFabric Core v1.1.0 - Candidate Integration Surface Consolidation and later, until any future promotion decision

The Scenario Run Index Surface is a Core-owned read-only JSON report that indexes simulation JSON reports produced by OrbitFabric Core.

It does not read plain-text logs.

It does not introduce coverage metrics.

It does not compute structured expectation accounting; it preserves simulation summary values already emitted by simulation JSON reports.

It does not introduce runtime behavior, ground behavior, graph behavior, plugin execution or Studio-specific APIs.

Generated by¶

orbitfabric export scenario-run-index \
  --simulation-reports examples/demo-3u/generated/reports \
  --json examples/demo-3u/generated/reports/scenario_run_index.json

Documented input directory:

examples/demo-3u/generated/reports

Documented output path:

examples/demo-3u/generated/reports/scenario_run_index.json

Output identity¶

{
  "kind": "orbitfabric.scenario_run_index",
  "index_version": "0.1-candidate"
}

The index_version value is a report format identifier.

It does not mean the surface is part of the v1.0.0 stable surface.

Purpose¶

The report answers:

Which Core simulation JSON reports are present in this reports directory?

It aggregates only simulation JSON reports with:

{
  "tool": "orbitfabric-sim"
}

Other JSON files in the same directory are ignored.

This allows the same reports directory to contain lint reports, dashboard summaries, coverage summaries or other Core-owned surfaces without turning them into scenario runs.

The index counts report files, not unique scenario identifiers.

If the same scenario is executed multiple times and each execution writes a distinct simulation JSON report, each report is indexed as a separate scenario run.

Top-level fields¶

index_version
kind
orbitfabric_version
source
boundaries
summary
runs

Boundary flags¶

The report declares its own boundaries.

Important flags include:

source_of_truth = simulation_json_reports
core_derived_report = true
read_only = true
contains_scenario_run_index = true
contains_coverage_metrics = false
contains_health_score = false
contains_expectation_accounting = false
contains_relationship_graph = false
contains_dependency_graph = false
contains_yaml_ast = false
contains_source_locations = false
contains_plugin_api = false
contains_studio_api = false
contains_runtime_behavior = false
contains_ground_behavior = false
derived_from_simulation_json = true
derived_from_logs = false

These flags are part of the report boundary.

They prevent consumers from treating the scenario run index as a coverage report, expectation accounting surface, graph, Studio API or runtime surface.

Summary section¶

The summary section contains aggregate indexed report counts.

Shape:

{
  "summary": {
    "total": 2,
    "passed": 2,
    "failed": 0
  }
}

Only simulation JSON reports indexed as scenario runs contribute to these counts.

These counts are file/run counts, not unique scenario counts.

Run records¶

Each run record includes:

report_file
report_path
mission
scenario
result
summary

The summary object is copied from the simulation JSON report summary with integer values preserved.

Current simulation summary values may include:

events
commands
mode_transitions
data_flow_evidence
expectations
passed_expectations
failed_expectations

The run record does not include timeline entries, event records, command records, mode transition records, data-flow evidence records or final state.

Those details remain in the original simulation JSON report.

Duplicate scenario identifiers¶

The scenario run index does not deduplicate by mission or scenario.

This is intentional.

Different report files may represent separate executions of the same scenario.

Consumers that need unique scenario views must derive those views explicitly from the indexed run records without changing the meaning of the Core report.

Log exclusion¶

Plain-text simulation logs are intentionally excluded.

The scenario run index is derived from simulation JSON reports only.

This preserves the rule:

machine-readable evidence must come from machine-readable Core reports

Logs remain human-oriented preview artifacts.

Coverage boundary¶

The scenario run index does not provide coverage.

It provides one input consumed by the dedicated v1.1.0 candidate coverage_summary.json surface, but does not compute:

scenario coverage
command coverage
event coverage
mode transition coverage
data product coverage
relationship coverage
expectation coverage

Coverage is defined separately through the Core-owned candidate coverage_summary.json surface.

Compatibility posture¶

scenario_run_index.json is introduced as a candidate post-v1 Core-owned structured surface and consolidated in v1.1.0.

It is not part of the original v1.0.0 stable surface.

Future promotion to a stronger compatibility class requires a separate reviewed decision and, if appropriate, golden signature protection for selected contract-significant fields.

Non-goals¶

The scenario run index does not provide:

coverage metrics
model completeness score
mission health score
new structured expectation accounting
relationship graph behavior
dependency graph behavior
Studio-specific API
plugin execution

Final statement¶

The scenario run index is the Core-owned bridge between individual simulation JSON reports and the dedicated v1.1.0 candidate coverage summary.

It is deliberately narrow:

read simulation JSON reports
index scenario run summaries
ignore unrelated JSON files
leave coverage computation to coverage_summary.json