Development Guide¶
This document explains how to work on OrbitFabric locally.
OrbitFabric is currently released at:
v1.1.0 - Candidate Integration Surface Consolidation
The stable Mission Data Contract baseline remains:
v1.0.0 - Stable Mission Data Contract
Development work after v1.0.0 must preserve the narrow Mission Data Contract scope and follow the release compatibility policy. v1.1.0 candidate integration surfaces are Core-owned, but they are not promoted to the original v1.0.0 stable compatibility class.
Requirements¶
OrbitFabric currently targets:
Python 3.11+
The CI validates Python 3.11 and Python 3.12.
The C++17 host-build smoke validation generated by the runtime profile additionally requires:
CMake
A C++17-capable compiler
Development tools are installed through the project optional dependency group:
.[dev]
Setup¶
From the repository root:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Verify installation:
orbitfabric --version
orbitfabric --help
Expected current package version:
orbitfabric 1.1.0
Local Quality Checks¶
Run:
ruff check .
pytest
mkdocs build --strict
Expected current baseline:
ruff check . -> All checks passed
pytest -> passing
mkdocs build --strict -> passing
Verify the v1.0 Stable State¶
Run mission lint:
orbitfabric lint examples/demo-3u/mission/ \
--json examples/demo-3u/generated/reports/lint_report.json
Export the v1.0 stable Core-owned structured surfaces:
orbitfabric export model-summary examples/demo-3u/mission/ \
--json examples/demo-3u/generated/reports/model_summary.json
orbitfabric export entity-index examples/demo-3u/mission/ \
--json examples/demo-3u/generated/reports/entity_index.json
orbitfabric export relationship-manifest examples/demo-3u/mission/ \
--json examples/demo-3u/generated/reports/relationship_manifest.json
Review the v1.0 references:
v1.0 Stable Surface Decision
v1.0 Demo Evidence Chain
Golden Output and Regression Confidence Policy
v1.0 Compatibility and Migration Notes
Release Compatibility Policy
Extensibility Boundary Contract
Generate documentation:
orbitfabric gen docs examples/demo-3u/mission/
Generate the dedicated data-flow evidence reference:
orbitfabric gen data-flow examples/demo-3u/mission/ \
--output-file examples/demo-3u/generated/docs/data_flow.md
Generate runtime-facing contract bindings and validate the host-build smoke target:
orbitfabric gen runtime examples/demo-3u/mission/
cmake -S examples/demo-3u/generated/runtime/cpp17 -B examples/demo-3u/generated/runtime/cpp17/build
cmake --build examples/demo-3u/generated/runtime/cpp17/build
Generate ground-facing integration artifacts:
orbitfabric gen ground examples/demo-3u/mission/
Run the demo scenarios:
orbitfabric sim examples/demo-3u/scenarios/battery_low_during_payload.yaml \
--json examples/demo-3u/generated/reports/battery_low_during_payload_report.json \
--log examples/demo-3u/generated/logs/battery_low_during_payload.log
orbitfabric sim examples/demo-3u/scenarios/payload_data_flow_evidence.yaml \
--json examples/demo-3u/generated/reports/payload_data_flow_evidence_report.json \
--log examples/demo-3u/generated/logs/payload_data_flow_evidence.log
Expected results:
lint -> Result: PASSED
export model-summary -> Result: PASSED
export entity-index -> Result: PASSED
export relationship-manifest -> Result: PASSED
gen docs -> Result: PASSED
gen data-flow -> Result: PASSED
gen runtime -> Result: PASSED
cmake build -> passing
gen ground -> Result: PASSED
sim -> Result: PASSED
Verify the v1.1 Candidate Integration Surfaces¶
Export the post-v1 candidate Core-owned integration surfaces:
orbitfabric export dashboard-summary examples/demo-3u/mission/
orbitfabric export scenario-run-index \
--simulation-reports examples/demo-3u/generated/reports \
--json examples/demo-3u/generated/reports/scenario_run_index.json
orbitfabric export coverage-summary examples/demo-3u/mission/
With omitted output paths, mission-based commands write under the mission workspace:
examples/demo-3u/generated/reports/dashboard_summary.json
examples/demo-3u/generated/reports/coverage_summary.json
These surfaces are Core-owned candidate outputs consolidated in v1.1.0.
They must not be treated as dashboard backend behavior, Studio API behavior, OpenOBSW/OpenSVF-specific generation, graph behavior, runtime behavior or ground behavior.
Generated Outputs¶
For the demo mission, mission-based commands write omitted generated artifact paths under:
examples/demo-3u/generated/
├── docs/
├── reports/
├── logs/
├── runtime/
└── ground/
Explicit user-provided output paths are preserved exactly as provided.
These files are reproducible outputs.
They are not the source of truth and should normally not be committed.
The source of truth is:
examples/demo-3u/mission/*.yaml
examples/demo-3u/scenarios/*.yaml
Generated runtime-facing contract bindings are disposable unless explicitly classified otherwise.
Generated ground-facing integration artifacts are disposable unless explicitly classified otherwise.
Generated Markdown documentation is disposable.
Plain-text logs are human-oriented and non-contractual.
Core-owned structured surfaces are derived from the validated Mission Model or from Core-generated structured outputs.
The stable v1.0.0 Core-owned structured surfaces are:
model_summary.json
entity_index.json
relationship_manifest.json
The v1.1.0 candidate Core-owned integration surfaces are:
dashboard_summary.json
scenario_run_index.json
coverage_summary.json
simulation JSON structured expectation accounting
The v1.0 golden signatures protect selected contract-significant fields of the stable surfaces.
They do not freeze full generated JSON files, absolute paths, human-oriented output, Markdown wording, generated runtime bindings, generated ground dictionaries or disposable artifact formatting.
User implementation code and downstream integration code must live outside generated/.
Development Order¶
For new behavior, follow this order:
1. update or define the Mission Model semantics
2. add or update lint rules
3. add tests
4. update generated docs or reports if needed
5. update runtime-facing, ground-facing, introspection, entity-index, relationship or candidate-surface exporters if needed
6. update user-facing documentation
After v1.0.0, any change to a selected stable surface must include explicit compatibility or migration notes.
Do not add simulator behavior that is not represented in the Mission Model.
Do not add generated artifacts that bypass validation.
Do not add runtime or ground integration artifacts before the relevant contract layer exists.
Do not add plugin execution mechanisms before Core-owned structured surfaces and plugin boundaries are explicitly defined.
Do not turn the Extensibility Boundary Contract into metadata schema, plugin discovery, plugin loading or plugin execution without a separate architectural review.
Do not put user code inside generated runtime bindings.
Do not present generated ground artifacts as live ground behavior.
Do not present Core-owned structured surfaces as relationship graphs, dependency graphs, plugin APIs, runtime behavior, ground behavior or Studio-specific APIs.
Documentation Site¶
Build the documentation site locally:
mkdocs build --strict
Preview locally:
mkdocs serve
The public site is deployed by the GitHub Pages workflow after pushes to main.
Clean-Room Reminder¶
Do not use private mission data, proprietary code, private packet formats, real operational logs or NDA-protected material.
See:
docs/CLEAN_ROOM_POLICY.md