Entity Index Surface¶
Status: Stable v1.0 surface
Surface version: 0.1
Default path: generated/reports/entity_index.json
OrbitFabric v0.8.2 introduced the first Core-owned entity index surface.
The surface is:
entity_index.json
It answers one deliberately narrow question:
What contract entities are defined in this mission?
In v1.0.0, this surface is part of the stable narrow Mission Data Contract surface.
Purpose¶
The Entity Index Surface gives downstream tools a stable, machine-readable way to inspect entity-level Mission Data Contract definitions without reconstructing semantics from raw files.
Downstream tools should not independently infer entity records by parsing:
raw YAML files
generated documentation
generated runtime artifacts
generated ground artifacts
human-oriented CLI output
The Core loads the Mission Model.
The Core validates the Mission Model.
The Core owns the meaning of Mission Data Contract entities.
The Core exports the entity index surface.
CLI¶
Generate an entity index report with:
orbitfabric export entity-index examples/demo-3u/mission/ \
--json generated/reports/entity_index.json
Default output:
generated/reports/entity_index.json
Output kind¶
The generated JSON report uses:
{
"kind": "orbitfabric.entity_index",
"index_version": "0.1"
}
Top-level structure¶
The report contains:
index_version
kind
orbitfabric_version
mission
source
boundaries
counts
domains
entities
mission¶
The mission section includes:
id
name
model_version
source¶
The source section includes:
mission_dir
This path identifies the Mission Model directory used to produce the report.
boundaries¶
The boundaries section explicitly declares what this report is and is not.
Current boundary flags include:
source_of_truth: mission_model
core_derived_report: true
read_only: true
contains_entity_index: true
contains_entity_records: true
contains_relationship_manifest: 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
counts¶
The counts section contains:
total_entities
domains
counts.domains maps each indexed domain to the number of entity records exported for that domain.
Domains that are summarized but not entity-indexed, such as mode_transitions and policies, have an entity count of 0.
domains¶
The domains section contains one record per supported contract domain.
Each domain record includes:
id
display_name
source_file
required
present
indexed
model_count
entity_count
count_provenance
model_count describes the count represented in the loaded Mission Model.
entity_count describes the number of entity records exported for that domain.
For domains without stable entity IDs, indexed is false and entity_count is 0.
entities¶
The entities section contains one record per indexed contract entity.
Each entity record includes:
id
domain
entity_type
display_name
source_file
provenance
required_domain
present
Entity records are derived from the loaded Mission Model.
They are not generated by scanning raw YAML files.
Indexed entity domains¶
The entity index includes stable entity records for:
spacecraft
subsystems
modes
telemetry
commands
events
faults
packets
payloads
data_products
contact_profiles
link_profiles
contact_windows
downlink_flows
command_sources
commandability_rules
autonomous_actions
recovery_intents
The following domains are summarized but do not produce entity records:
mode_transitions
policies
This is intentional.
They do not currently expose stable entity IDs in the Mission Model, so the Core does not create synthetic entity records for them.
Example entity record¶
Example shape:
{
"id": "payload.start_acquisition",
"domain": "commands",
"entity_type": "command",
"display_name": "payload.start_acquisition",
"source_file": "commands.yaml",
"provenance": "loaded_mission_model",
"required_domain": true,
"present": true
}
The exact values depend on the loaded Mission Model.
Boundary¶
The Entity Index Surface is not:
a generated runtime binding
a generated ground artifact
a relationship manifest
a relationship graph
a dependency graph
a source map
a YAML AST export
a plugin API
a Studio-specific API
a runtime behavior surface
a ground behavior surface
It does not expose inferred relationships.
It does not expose line or column locations.
It does not introduce new Mission Model semantics.
It does not create synthetic entity IDs for domains that do not own stable IDs.
Relationship to model summary and relationship surfaces¶
model_summary.json, entity_index.json and relationship_manifest.json are separate Core-owned surfaces.
model_summary.json answers:
What contract domains are present in this mission?
entity_index.json answers:
What contract entities are defined in this mission?
relationship_manifest.json answers:
How are indexed mission contract entities related?
The model summary is domain-level.
The entity index is entity-level.
The relationship manifest is relationship-level.
None of these surfaces is a relationship graph or plugin API.
Final position¶
entity_index.json is a stable v1.0 Core-derived report.
It is deterministic, inspectable and machine-readable.
It exists so downstream tools can navigate Mission Data Contract entities without becoming a second source of truth.