---
title: Capability Contract Boundary
status: draft
maturity: hypothesis
families: [composition, execution]
scales: [L4]
admission: research-candidate-only
---

# Capability Contract Boundary

Context: a UI capability (e.g. a customer editor, a document viewer) is consumed by
one or more independently evolving host applications, possibly across frameworks or
teams. The host needs a stable way to configure, observe and command the capability
without depending on its internal framework, state library or rendering technology.

Proposed solution: declare the capability's public surface as an explicit, versioned
semantic contract — inputs/configuration, emitted events, invokable commands, and
host-provided presentation slots — separately from whichever runtime-isolation
mechanism (a plain package, a Custom Element, a Module Federation remote, a
micro-frontend, an iframe) carries it. The contract is the thing consumers depend on
and version against; the isolation mechanism is an implementation detail that can
change without necessarily breaking the contract.

Result: hosts can swap or upgrade a capability's implementation without renegotiating
its interface, and the interface can be reasoned about independently of deployment
topology. Declaring a contract does not by itself provide runtime isolation, dependency
negotiation or compatibility checking — those still come from whatever mechanism
implements it (see Evidence). A contract with no enforcement is only documentation.

Evidence: [source review](../reviews/CapabilityContractSources.md) CC01–CC03 locates
two real, independently documented substrate mechanisms — Custom Elements'
attribute/lifecycle callbacks (CC01) and Module Federation's expose/consume module
contract (CC02) — and establishes that neither defines a semantic capability contract
itself (CC03); one would be authored on top of either. No known use of an explicit
capability contract, as distinct from its substrate mechanisms, has been located.
Prompted by a non-primary AI-chat lead that is explicitly not cited as evidence; see
[SourceCatalog.md](../catalog/SourceCatalog.md).

Alternative: an ad hoc, framework-typed component API (e.g. React props/callbacks)
when every consumer already shares the same framework and version, making a
framework-neutral contract layer unnecessary overhead.

Proposed relations: [Independent Feature Boundary](IndependentFeatureBoundary.md)
governs release/activation cadence and may carry a capability contract without being
one; [Vertical Feature Slice](VerticalFeatureSlice.md) governs source-code grouping,
a different concern. Neither entails this pattern nor is entailed by it.

Next test: pin one real Custom Element library and one real Module Federation
example; compare what each actually enforces about a component's declared
inputs/events/commands versus what a hand-authored capability-contract layer would
need to add on top. All relations are research proposals; no canonical identity or
admitted graph edges. The next test is planned, not executed.