ADR-0015 - Extensibility Boundary Contract, No Execution¶
Status: Accepted
Date: 2026-05-16
Context¶
OrbitFabric Core is currently at the v0.10.1 - Documentation and Published Site Consistency baseline.
The next roadmap milestone is:
v0.11.0 - Extensibility Boundary Contract, no execution
OrbitFabric already exposes a Core-owned structured surface chain:
model_summary.json -> domain-level contract introspection
entity_index.json -> entity-level contract indexing
relationship_manifest.json -> relationship-level contract records
These surfaces are deterministic, read-only, machine-readable and derived from the validated Mission Model.
They exist so downstream tools can consume Core-owned contract semantics without reconstructing meaning from raw YAML, generated files, textual CLI output or UI state.
ADR-0014 established the v0.9 boundary between plugin planning, relationship manifest planning and downstream relationship consumption.
v0.11.0 must now make the extensibility boundary explicit without introducing plugin execution.
This is necessary because future extensions are useful only if they preserve the central OrbitFabric rule:
Mission Model is the source of truth.
Core owns contract semantics.
Downstream tools consume Core-owned surfaces.
Extensions may add outputs, but must not redefine the contract.
Without an explicit boundary, plugin terminology can easily be misread as permission to add private semantics, custom execution, runtime behavior, ground behavior or downstream-specific APIs.
Decision¶
v0.11.0 defines an extensibility boundary contract without execution.
The accepted posture is:
extensibility is descriptive before it is executable
OrbitFabric may document future extension metadata, capability declarations, provenance requirements and output ownership rules.
OrbitFabric must not introduce plugin discovery, plugin loading, plugin execution, custom lint plugin execution, custom generator plugin execution, remote registries, marketplaces, runtime extension behavior or ground extension behavior in v0.11.0.
The v0.11.0 extensibility boundary must be treated as a contract about ownership, provenance and allowed future directions, not as an implementation of an extension runtime.
Core Ownership Rules¶
The Core owns Mission Data Contract 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 surfaces only after the Core has produced them from the validated Mission Model.
A future extension must not become a second source of truth.
Extension Ownership Rules¶
Future extension-owned outputs must be distinguishable from Core-owned outputs.
A future extension output must not be presented as a Core output unless it is generated by Core and documented as a Core-owned surface.
The following categories must remain distinguishable:
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 because downstream consumers must know whether a record carries Core contract semantics or extension-specific interpretation.
Provenance Requirements¶
Future extension metadata or extension-generated outputs must declare provenance clearly.
At minimum, any 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 fields are descriptive expectations only in this ADR.
This ADR does not introduce a metadata schema, parser, loader, validator, registry or command.
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.
Allowed Future Extension Directions¶
After this boundary is documented and reviewed, future milestones may consider descriptive extension capabilities such as:
extension metadata declarations
extension capability declarations
extension provenance reports
extension-generated artifact manifests
extension compatibility declarations
extension diagnostics that are clearly not Core diagnostics
These directions are allowed only if they remain derived from or anchored to Core-owned surfaces.
They do not imply execution in v0.11.0.
Explicit Non-goals for v0.11.0¶
This ADR 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
All of these require separate architectural decisions and implementation PRs after the Mission Data Contract is sufficiently stable.
Downstream Tool Boundary¶
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.
Compatibility Consequences¶
The extensibility boundary becomes compatibility-sensitive documentation before v1.0.0.
Changes to the following require explicit review:
Core ownership rules
extension ownership rules
provenance requirements
semantic override ban
allowed future extension categories
v0.11.0 non-goals
This ADR does not provide a stable v1.0 guarantee by itself.
It prepares the project to decide, during v0.12.0 release candidate hardening, which extensibility-related documents or metadata expectations should become stable.
Consequences¶
OrbitFabric can discuss extensibility without becoming a plugin execution platform.
Future extension work is constrained to consume Core-owned surfaces and preserve Core semantic authority.
Downstream consumers get a clear rule for distinguishing Core output from extension output.
The Mission Model remains the source of truth.
The Core remains the owner of Mission Data Contract semantics.
Extensions may add value at the edges, but they do not redefine the contract.
Acceptance Criteria¶
This ADR is satisfied when the project makes the following explicit:
v0.11.0 defines extensibility boundaries, not plugin execution
Core-owned outputs and extension-owned outputs must remain distinguishable
future extension artifacts require clear provenance
extensions must not override Core semantics
extensions must consume Core-owned surfaces instead of reconstructing semantics privately
Studio and other downstream tools remain consumers, not semantic owners
Final Position¶
OrbitFabric v0.11.0 protects the Mission Data Contract by defining how extensibility may exist around it.
Extensibility starts as a boundary contract.
Execution is out of scope.
Core remains authoritative.