Coverage Summary Surface¶
Status: Candidate post-v1 Core-owned structured surface
Scope: coverage metrics derived from Core structured outputs
Applies to: OrbitFabric Core after v1.0.0 - Stable Mission Data Contract
The Coverage Summary Surface is a Core-owned read-only JSON report that emits limited coverage metrics derived from Core structured outputs.
It does not read plain-text logs.
It does not scan raw YAML.
It does not introduce a mission health score, model completeness score, runtime behavior, ground behavior, graph behavior, plugin execution or Studio-specific APIs.
Generated by¶
orbitfabric export coverage-summary examples/demo-3u/mission/ \
--entity-index generated/reports/entity_index.json \
--relationship-manifest generated/reports/relationship_manifest.json \
--scenario-run-index generated/reports/scenario_run_index.json \
--json generated/reports/coverage_summary.json
If the input and output options are omitted, the default paths are mission-workspace relative.
For examples/demo-3u/mission/, the default paths are:
examples/demo-3u/generated/reports/entity_index.json
examples/demo-3u/generated/reports/relationship_manifest.json
examples/demo-3u/generated/reports/scenario_run_index.json
examples/demo-3u/generated/reports/coverage_summary.json
Explicit --entity-index, --relationship-manifest, --scenario-run-index and --json paths are preserved unchanged.
coverage-summary is mission-based and therefore follows the workspace-relative generated artifact default rule.
Output identity¶
{
"kind": "orbitfabric.coverage_summary",
"coverage_version": "0.1-candidate"
}
The coverage_version value is a report format identifier.
It does not mean the surface is part of the original v1.0.0 stable surface.
Source inputs¶
The coverage summary is derived from structured Core-owned inputs:
entity_index.json
relationship_manifest.json
scenario_run_index.json
simulation JSON reports referenced by scenario_run_index.json
It must not be derived from:
plain-text logs
human-oriented CLI output
generated Markdown documentation
generated runtime bindings
generated ground dictionaries
raw YAML scanning by downstream tools
UI state
private Studio heuristics
Top-level fields¶
coverage_version
kind
orbitfabric_version
mission
source
boundaries
scenario_runs
entity_coverage
expectation_coverage
relationship_coverage
unsupported
Boundary flags¶
The report declares its own boundaries.
Important flags include:
source_of_truth = core_structured_outputs
core_derived_report = true
read_only = true
contains_coverage_metrics = true
contains_health_score = false
contains_model_completeness_score = 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
coverage_derived_from_entity_index = true
coverage_derived_from_relationship_manifest = true
coverage_derived_from_scenario_run_index = true
coverage_derived_from_simulation_json = true
coverage_derived_from_logs = false
These flags are part of the report boundary.
They prevent consumers from treating coverage as runtime validation, ground validation, formal verification, health scoring or graph behavior.
Scenario runs¶
The scenario_runs section copies the aggregate run counts from scenario_run_index.json.
Shape:
{
"scenario_runs": {
"total": 1,
"passed": 1,
"failed": 0
}
}
These counts are indexed simulation report counts, not unique scenario identifiers.
Entity coverage¶
The first candidate version supports entity coverage for domains with direct evidence in current simulation JSON reports:
commands
events
data_products
Entity coverage is computed as:
covered IDs observed in simulation JSON reports / declared IDs from entity_index.json
Example shape:
{
"entity_coverage": {
"commands": {
"total": 4,
"covered": 2,
"uncovered": 2,
"coverage_ratio": 0.5,
"covered_ids": [],
"uncovered_ids": []
}
}
}
A ratio is emitted only when Core emits both numerator and denominator.
Expectation coverage¶
Expectation coverage is derived from the structured expectations object in simulation JSON reports.
It includes:
total
passed
failed
pass_ratio
by_type
This is scenario expectation accounting.
It is not formal verification.
It is not proof coverage.
It is not runtime telemetry validation.
Relationship coverage¶
The first candidate version supports only relationship families with direct evidence in current simulation JSON reports:
data_product_produced_by_payload
data_product_produced_by_subsystem
downlink_flow_includes_data_product
These are covered when data-flow evidence records prove that the data product appeared in scenario evidence.
Unsupported relationship families are listed in the unsupported.relationship_types section.
This avoids pretending that all relationship families can be covered from the current simulation report shape.
Unsupported domains and relationships¶
The unsupported section declares coverage areas that are not computed by this report version.
This is intentional.
Consumers must not invent private coverage metrics for unsupported domains or relationship families.
Compatibility posture¶
coverage_summary.json is introduced as a candidate post-v1 Core-owned structured surface.
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 coverage summary does not provide:
mission health score
model completeness score
flight readiness score
runtime validation
live telemetry validation
ground execution validation
formal verification
relationship graph behavior
dependency graph behavior
Studio-specific API
plugin execution
Final statement¶
The coverage summary is the first Core-owned coverage surface.
It is deliberately narrow:
use Core structured outputs only
emit numerator and denominator
mark unsupported domains explicitly
avoid log parsing and UI heuristics