---
title: "RFC: additive plugin and registry ABI under protocol v1"
image: "https://adonia.pages.dev/og.png"
version: "next"
---

> Documentation Index
> Fetch the complete documentation index at: https://adonia.pages.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

1. server plugins are defined with `definePlugin()` and attached in order with `Panel.plugins()`;
2. the server hook event set and six addressable pipeline stages are closed for protocol v1;
3. 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.

Source: https://adonia.pages.dev/rfcs/plugin-registry-abi/index.mdx