Extensibility Boundary Contract¶
Status: Active v1.0 governance contract
Scope: extensibility boundary classification, no execution
Applies to: future extension metadata, extension-owned outputs and downstream consumers from v1.0.0 - Stable Mission Data Contract onward
This page documents the OrbitFabric extensibility boundary.
It is a stable v1.0 governance surface.
It does not introduce plugin discovery, plugin loading, plugin execution, custom lint plugin execution, custom generator plugin execution, new Mission Model semantics, new YAML fields, new generated Core surfaces, JSON Schema publication, schema migration tooling, runtime behavior, ground behavior or Studio-specific APIs.
1. Purpose¶
OrbitFabric Core is a Mission Data Contract framework.
Its extensibility model must preserve that identity.
The purpose of this document is to make explicit how future extensions may relate to Core-owned semantics without becoming a second source of truth.
The central rule is:
Mission Model is the source of truth.
Core owns Mission Data Contract semantics.
Extensions may add value at the edges.
Extensions must not redefine the contract.
The accepted v1.0 posture is:
extensibility is descriptive before it is executable
2. Current Core-owned surface chain¶
OrbitFabric Core exposes these Core-owned structured surfaces:
model_summary.json -> What contract domains are present?
entity_index.json -> What contract entities are defined?
relationship_manifest.json -> How are indexed mission contract entities related?
These surfaces are:
Core-derived
read-only
deterministic
machine-readable
derived from the validated Mission Model
safe for downstream inspection
not the source of truth
The Mission Model remains the source of truth.
The Core owns the interpretation of that Mission Model.
Downstream tools and future extensions must consume Core-owned surfaces instead of reconstructing Mission Data Contract semantics from raw YAML, generated files, terminal output or UI state.
3. Core-owned semantics¶
The following remain Core-owned:
Mission Model loading
structural validation
semantic linting
scenario validation
scenario evidence semantics
runtime-facing contract binding semantics
ground-facing artifact semantics
model_summary.json semantics
entity_index.json semantics
relationship_manifest.json semantics
stability and compatibility classification
release compatibility policy
A future extension must not override, replace, mutate or privately reinterpret these semantics.
A future extension may consume Core-owned outputs only after the Core has produced them from the validated Mission Model.
4. Extension-owned outputs¶
Future extension-owned outputs must be distinguishable from Core-owned outputs.
The following categories must remain separate:
Core output
Core diagnostic
Core generated artifact
Core-owned structured surface
extension metadata
extension diagnostic
extension-generated artifact
extension compatibility declaration
This distinction is mandatory.
A downstream consumer must be able to determine whether an artifact carries Core contract semantics or extension-specific interpretation.
An extension-owned output must not be presented as a Core output unless it is generated by OrbitFabric Core and documented as a Core-owned surface.
5. Provenance expectations¶
Future extension metadata or extension-generated outputs should declare provenance clearly.
At minimum, a future extension-owned artifact should be able to describe:
extension identity
extension version
compatible OrbitFabric surface or contract version
input Core-owned surfaces consumed
output artifact kind
output ownership
whether the output is diagnostic, descriptive or generated
whether the output is safe for downstream inspection
These are descriptive expectations for future work.
This document does not define a metadata schema.
It does not define field names, JSON structure, validation rules, a file path, parser, loader, registry or CLI command.
6. Non-normative future metadata guidance¶
Future extension metadata, if introduced by a later milestone, should remain descriptive, inspectable and non-authoritative with respect to Core semantics.
This section is intentionally non-normative.
It is guidance for future design work, not a schema commitment.
A future metadata declaration may need to answer these engineering questions:
Who produced this extension-owned artifact?
Which OrbitFabric Core version or surface version was it designed around?
Which Core-owned surfaces were consumed as input?
What kind of artifact was produced?
Who owns the meaning of the produced artifact?
Is the result descriptive, diagnostic or generated?
Is the result safe for downstream inspection?
Does the result claim any authority over Core semantics?
The expected answer to the last question must be:
No.
Future metadata should classify intent rather than enable execution.
Useful descriptive dimensions may include:
identity
compatibility
input surfaces
output ownership
artifact intent
diagnostic scope
downstream inspection safety
non-authority over Core semantics
These dimensions are not field names.
They are not a JSON shape.
They are not a metadata manifest format.
They are not a validation contract.
They are not a plugin API.
They are only design constraints for future reviewed work.
A future PR that turns any of these dimensions into a concrete file format, schema, CLI command, loader or execution behavior must be treated as a separate architectural step.
7. Semantic override ban¶
A future extension must not silently override Core semantics.
Forbidden behaviors include:
changing Mission Model meaning after Core loading
reinterpreting raw YAML when Core already exposes loaded semantics
mutating Core-owned structured surfaces
rewriting Core validation results
reclassifying Core lint diagnostics as authoritative replacements
adding relationship semantics as if they were Core-owned
changing runtime-facing contract binding semantics
changing ground-facing artifact semantics
presenting extension output as Core output
If a future extension detects a disagreement with Core output, it may report an extension diagnostic.
It must not replace the Core result.
8. Allowed descriptive extension categories¶
Future milestones may consider descriptive extension categories such as:
extension metadata declarations
extension capability declarations
extension provenance reports
extension-generated artifact manifests
extension compatibility declarations
extension diagnostics clearly marked as extension-owned
These categories are allowed only if they remain derived from or anchored to Core-owned surfaces.
They do not imply execution.
They do not imply a plugin runtime.
9. Disallowed capabilities¶
The v1.0 extensibility boundary does not introduce:
plugin discovery
plugin loading
plugin execution
custom lint plugin execution
custom generator plugin execution
dynamic extension runtime
third-party code execution
remote plugin registry
plugin marketplace
extension installation
extension dependency resolution
relationship graph
dependency graph
runtime behavior
ground behavior
Studio-specific API
new Mission Model semantics
new YAML fields
new generated Core surface
schema migration tooling
JSON Schema publication
These items require separate architectural decisions and implementation PRs after the Mission Data Contract is sufficiently stable.
10. Downstream consumer rule¶
Downstream tools, including OrbitFabric Studio, must consume Core-owned structured surfaces.
They must not reconstruct contract semantics from:
raw YAML
generated Markdown
generated runtime files
generated ground files
stdout or stderr text
file names
ID naming conventions
UI state
private extension assumptions
A downstream tool may inspect extension-owned artifacts only if those artifacts are explicitly marked as extension-owned and do not claim Core authority.
Studio-specific requirements must not become Core API requirements.
11. Relationship to generated surface stability¶
This document complements the Generated Surfaces Stability reference.
Generated Surfaces Stability classifies current generated and exported surfaces.
This document defines how future extension-owned outputs must remain distinguishable from those Core-owned surfaces.
The relevant boundary is:
Core-owned surface -> carries Core Mission Data Contract semantics
extension-owned output -> carries extension-specific interpretation or diagnostics
An extension may consume a Core-owned surface.
An extension must not promote its own output to Core-owned status.
12. Relationship to ADR-0015¶
ADR-0015 records the original architectural decision for the extensibility boundary.
This reference page makes that decision easier to consume from the public documentation.
ADR-0015 is the decision record.
This page is the reference contract.
If the two diverge, the project must resolve the discrepancy explicitly.
13. Compatibility-sensitive changes¶
The following changes are compatibility-sensitive after v1.0.0:
- changing Core ownership rules;
- changing extension ownership rules;
- weakening the semantic override ban;
- allowing extension outputs to masquerade as Core outputs;
- removing provenance expectations;
- converting non-normative metadata guidance into a concrete schema without a separate architectural review;
- adding execution semantics to the boundary;
- adding Studio-specific API expectations to the Core boundary;
- treating extension diagnostics as Core diagnostics;
- allowing extensions to reconstruct semantics from raw YAML where Core-owned surfaces exist.
Compatibility-sensitive does not mean forbidden.
It means the change must be explicit, reviewed and documented.
14. Final statement¶
The v1.0 extensibility boundary stabilizes these rules:
Core remains semantic owner.
Mission Model remains source of truth.
Extensions consume Core-owned surfaces.
Extension-owned outputs remain distinguishable from Core-owned outputs.
Semantic override remains forbidden.
Execution remains outside the stable v1.0 Core boundary unless separately designed and accepted.
v1.0.0 stabilizes the Mission Data Contract without turning OrbitFabric into a plugin execution platform.