Development Guide¶
This document explains how to work on OrbitFabric locally.
OrbitFabric is currently released at:
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.
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.0.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 Current Stable State¶
Run mission lint:
orbitfabric lint examples/demo-3u/mission/ \
--json generated/reports/lint_report.json
Export the Core-owned structured surfaces:
orbitfabric export model-summary examples/demo-3u/mission/ \
--json generated/reports/model_summary.json
orbitfabric export entity-index examples/demo-3u/mission/ \
--json generated/reports/entity_index.json
orbitfabric export relationship-manifest examples/demo-3u/mission/ \
--json 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 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 generated/runtime/cpp17 -B generated/runtime/cpp17/build
cmake --build 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 generated/reports/battery_low_during_payload_report.json \
--log generated/logs/battery_low_during_payload.log
orbitfabric sim examples/demo-3u/scenarios/payload_data_flow_evidence.yaml \
--json generated/reports/payload_data_flow_evidence_report.json \
--log 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
Generated Outputs¶
Generated outputs are written under:
generated/
├── docs/
├── reports/
├── logs/
├── runtime/
└── ground/
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.
The current stable Core-owned structured surfaces are:
model_summary.json
entity_index.json
relationship_manifest.json
The v1.0 golden signatures protect selected contract-significant fields of these 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 or relationship 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 introduce schema migration tooling, JSON Schema publication, security enforcement semantics or Mission Model security domains without a separate architectural decision.
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