v1.0 Stable Surface Decision¶
Status: Accepted in v1.0.0
Scope: narrow stable Mission Data Contract surface
Applies to: OrbitFabric Core v1.0.0 - Stable Mission Data Contract
This page records the stable surface decision for v1.0.0 - Stable Mission Data Contract.
The decision is intentionally narrow.
OrbitFabric v1.0.0 stabilizes the Mission Data Contract core and selected machine-readable Core-owned surfaces.
It does not stabilize OrbitFabric as a flight software framework, ground segment, mission control system, visual modeling tool, plugin execution platform, packet standard implementation, security framework or tool-specific integration layer.
1. Decision principle¶
The v1.0.0 stable surface is limited to behavior and data shapes that are mature, documented, deterministic and central to the Mission Data Contract.
The guiding rule is:
Mission Model is the source of truth.
Core owns Mission Data Contract semantics.
Core-owned structured surfaces are derived from the validated Mission Model.
Downstream tools consume Core-owned structured surfaces.
Generated implementation-facing artifacts remain reproducible and disposable unless explicitly classified otherwise.
A surface is not stable only because it exists, is documented, appears in examples or is generated by CI.
A surface is stable in v1.0.0 only if it is listed in this decision or in a later reviewed release decision that explicitly amends this page.
2. Stable v1.0 Mission Data Contract surface¶
The following surfaces are accepted as the v1.0 stable surface.
| Surface | Stable commitment | Boundary |
|---|---|---|
| Mission Model documented contract semantics | Existing documented domains, field meanings, identifier rules, reference rules and controlled values are stable within the v1.0 compatibility policy. | This does not freeze YAML formatting, file ordering, comments or undocumented implementation internals. |
| Core structural validation | Loader and validation responsibilities are stable for documented Mission Model inputs. | This does not guarantee private Pydantic internals or Python object layout. |
| Core semantic lint diagnostic policy | Lint diagnostic codes, severities and documented meanings are compatibility-sensitive. Additive diagnostics remain allowed under the release policy. | This does not freeze human-oriented terminal wording. |
| Scenario YAML evidence inputs | Existing documented scenario structure and expectation semantics are stable as host-side contract evidence inputs. | This is not a dynamic simulator, operations runtime or real-time execution environment. |
| Lint JSON report | Top-level result fields, diagnostic record meaning and machine-readable status values are stable. | Terminal output remains human-oriented and non-contractual. |
| Simulation JSON report | Top-level result fields and data-flow evidence records are stable for documented scenario behavior. | Plain-text logs remain human-oriented and non-contractual. |
model_summary.json |
Stable Core-owned domain-level contract introspection surface. | It remains derived from the Mission Model and is not a second source of truth. |
entity_index.json |
Stable Core-owned entity-level index surface. | It is not a YAML AST export, source-location database or Studio-specific API. |
relationship_manifest.json |
Stable Core-owned narrow relationship record surface for admitted relationship families. | It is not a graph engine, dependency graph, layout format, runtime routing table or plugin API. |
| CLI command interface for documented workflows | Documented command names and options for linting, simulation, documentation generation, data-flow generation, runtime generation, ground generation and Core-owned exports are stable. | Human-readable stdout and stderr prose are not machine-readable contracts. |
| Release compatibility policy | Compatibility classes and note discipline are stable governance references for post-v1.0 maintenance. | This does not introduce migration tooling or compatibility scanners. |
| Extensibility boundary contract | Core ownership, extension ownership, downstream consumption and semantic override rules are stable boundary rules. | This does not introduce plugin discovery, plugin loading, plugin execution or metadata schema. |
3. Public preview surfaces in v1.0.0¶
The following surfaces remain public preview in v1.0.0.
They are documented and useful, but they are not part of the narrow stable v1.0 compatibility surface.
| Surface | v1.0 posture | Reason |
|---|---|---|
| CLI textual output | Public preview, human-oriented | Users may read it, but tools must consume JSON reports or Core-owned structured surfaces. |
orbitfabric inspect mission terminal output |
Public preview, human-oriented | Useful for inspection, not a machine contract. |
orbitfabric validate scenario terminal output |
Public preview, human-oriented | Pass or fail behavior matters more than exact wording. |
| Generated Markdown mission documentation | Public preview generated documentation | Human-reviewable output may evolve without changing contract semantics. |
| Demo mission narrative text | Public example | Examples demonstrate usage but are not full compatibility specifications by themselves. |
| Plain-text simulation logs | Public preview, human-oriented | Machine evidence lives in simulation JSON reports. |
| Generated C++17 runtime-facing bindings | Public preview disposable generated artifact | Useful contract-facing bindings, not a stable flight ABI or runtime. |
| Generated ground-facing dictionaries | Public preview disposable generated artifacts | Useful integration artifacts, not Yamcs, OpenC3, XTCE or live ground behavior. |
| Runtime and ground manifest files | Public preview generated manifests | Their semantics may be protected selectively later, but they are not selected for the first stable v1.0 core surface. |
4. Generated disposable artifacts¶
The following outputs remain generated disposable artifacts.
They must be reproducible from the validated Mission Model.
Users must not place handwritten implementation code inside generated output directories.
generated Markdown mission documentation
generated data-flow Markdown documentation
generated C++17 runtime-facing headers and source files
generated C++17 host-build smoke files
generated generic ground JSON dictionaries
generated generic ground CSV dictionaries
generated generic ground Markdown documentation
plain-text logs written under generated/logs
workflow-uploaded generated artifacts
Disposable does not mean unimportant.
It means the Mission Model remains authoritative and the generated artifact can be regenerated instead of hand-maintained.
5. Internal implementation details¶
The following areas remain internal implementation details in v1.0.0.
Python package module layout
private helper functions
private builder object identities
Pydantic internal representation not documented as a public contract
internal lint implementation structure
internal generator implementation structure
internal exporter implementation structure
test helper layout
workflow implementation details
local development scripts
These areas may change as long as the stable public behavior and stable machine-readable surfaces remain compatible.
6. Explicitly out of v1.0 scope¶
The following topics are explicitly out of the v1.0.0 stable Core scope.
XTCE exporter
XTCE-compliant mission database
Yamcs integration
OpenC3 integration
F Prime mapping
cFS integration
EDS generation
CCDD generation
CCSDS packet implementation
PUS service or subservice implementation
APID semantics
VCID semantics
packet binary layout
byte offsets
bit offsets
endianness
binary telemetry decoder generation
binary telecommand encoder generation
flight runtime behavior
ground runtime behavior
mission control behavior
operator console
telemetry archive
command uplink service
hardware abstraction layer
RTOS integration
relationship graph engine
dependency graph engine
visual modeling backend
Studio-specific API
plugin discovery
plugin loading
plugin execution
plugin metadata schema
plugin metadata parser
plugin metadata loader
plugin metadata validator
schema migration tooling
JSON Schema publication
Mission Model security domain
security YAML fields
authorization model
security enforcement semantics
These may be valid future work only after separate design, implementation and testing.
They must not be implied by the v1.0.0 stable Mission Data Contract release.
7. Golden signature implications¶
The v1.0.0 release includes golden signatures for selected contract-significant fields of these Core-owned structured surfaces:
model_summary.json
entity_index.json
relationship_manifest.json
Golden signatures protect contract meaning first:
top-level kind and version fields
mission identity
entity kinds
entity identifiers
relationship families
relationship endpoints
boundary flags
domain counts
selected relationship records
They do not freeze incidental human wording, Markdown prose, whitespace or disposable generated implementation formatting.
8. CI confidence anchors¶
The following checks remain release confidence anchors:
ruff check .
pytest
mkdocs build --strict
orbitfabric lint examples/demo-3u/mission/
orbitfabric gen docs examples/demo-3u/mission/
orbitfabric gen data-flow examples/demo-3u/mission/
orbitfabric sim examples/demo-3u/scenarios/battery_low_during_payload.yaml
orbitfabric sim examples/demo-3u/scenarios/payload_data_flow_evidence.yaml
orbitfabric export model-summary examples/demo-3u/mission/
orbitfabric export entity-index examples/demo-3u/mission/
orbitfabric export relationship-manifest examples/demo-3u/mission/
orbitfabric gen runtime examples/demo-3u/mission/
cmake -S generated/runtime/cpp17 -B generated/runtime/cpp17/build
cmake --build generated/runtime/cpp17/build
orbitfabric gen ground examples/demo-3u/mission/
CI confidence is not the same as a full-file committed golden-output baseline.
9. v1.0 demonstration use-case¶
The v1.0.0 demonstration focuses on the existing end-to-end Mission Data Contract chain.
The selected demonstration path is:
payload acquisition command
-> command expected effect
-> event evidence
-> data product
-> storage intent
-> downlink intent
-> eligible downlink flow
-> matching contact window
-> scenario evidence
-> runtime-facing bindings
-> ground-facing dictionaries
-> model_summary.json
-> entity_index.json
-> relationship_manifest.json
This use-case demonstrates OrbitFabric's current value without claiming compatibility with XTCE, Yamcs, OpenC3, F Prime, cFS, CCSDS, PUS or EDS.
The use-case is a proof of Mission Data Contract continuity.
It is not a flight runtime, ground runtime, live decoder, command encoder, mission database or tool-specific export.
10. Compatibility and migration posture¶
The v1.0.0 stable surface has no Mission Data Contract semantic migration impact from the v0.12.0 release candidate hardening baseline.
If a later PR changes one of the stable surfaces listed here, it must include a compatibility or migration note.
The note must identify:
surface
status
change type
compatibility impact
migration guidance
reason
scope boundary
No migration tooling, JSON Schema publication or schema version negotiation is introduced by this decision.
11. Public claim boundary¶
The v1.0.0 public claim is limited to this statement:
OrbitFabric provides a stable narrow Mission Data Contract surface for defining, validating, simulating, documenting, introspecting, indexing, relating and generating contract-facing artifacts from a small spacecraft Mission Model.
The v1.0.0 public claim must not say or imply:
XTCE compatible
Yamcs ready
OpenC3 ready
F Prime compatible
cFS compatible
CCSDS compliant
PUS compliant
flight ready
ground segment ready
security framework
plugin execution framework
relationship graph engine
mission control system
Future integrations require separate post-v1.0 milestones and tool-specific tests.
12. Final decision¶
The v1.0.0 stable surface is intentionally narrow, testable and defensible.
The stable core is:
Mission Model semantics
validation and lint policy
scenario evidence semantics
machine-readable JSON reports
Core-owned structured surfaces
release compatibility governance
extensibility boundary governance
Everything else remains preview, disposable, internal or out of scope unless explicitly promoted by a future reviewed decision.
This is the v1.0 posture for OrbitFabric Core.