RFC: additive plugin and registry ABI under protocol v1

Status: Accepted for 1.0
Date: 2026-07-27
Protocol impact: additive; protocol version remains 1

Decision

Adonia freezes three coordinated extension boundaries for 1.0:

server plugins are defined with definePlugin() and attached in order with Panel.plugins();
the server hook event set and six addressable pipeline stages are closed for protocol v1;
client plugins extend a ComponentRegistry through use() and named registry maps.

The ordered plugin list is behavioral input to descriptor/index-plan caching. Registry additions affect resolution only for the host registry instance. Unknown component types render the safe fallback and emit registry telemetry; they never change the wire version.

Protocol impact

Plugin-mutated descriptors still satisfy the existing DescriptorNode shape. Custom field, cell, filter, layout, display, and widget identifiers use the already-open type: string registry key and props: JsonObject. Tenant, nesting, locale, and direction data is optional/additive. Consequently existing v1 clients can ignore additions they do not understand and still hard-fail on an actual protocolVersion mismatch.

A future change that removes or reinterprets a required wire key, changes a closed JsonLogic operator’s semantics, or makes a currently optional key required needs protocol v2. Adding a plugin hook or registry map is a semver-minor ecosystem-ABI change and requires this RFC’s conformance fixtures to be extended; it does not by itself require protocol v2 when the wire remains additive.

Compatibility obligations

Hook handlers run in registration order; plugin order participates in cache identity.
Runtime hook isolation and record-transaction propagation follow the plugin conformance contract.
Registry plugin installation is ordered and per registry; named plugins provide stable identity.
Protocol fixtures remain byte-compatible and PROTOCOL_VERSION/SUPPORTED_PROTOCOL_VERSION remain 1.
The release gate inventories hook names, pipeline stages, registry maps, export maps, and protocol fixtures before publishing.