Canonical vocabulary for the portable contribution ecosystem. Behavior and contracts are defined in ARCHITECTURE.md. The decision history records the owner review; earlier proposal packets are historical.
| Term | Definition | Distinction |
|---|---|---|
| Capability | A declared backend service contract offered by a provider, consisting of named operations | A contract does not imply a currently available implementation |
| Capability descriptor | An imported definition containing the capability ID, mandatory numeric contract version and operation schemas | Separate from a service definition or running service |
| Contract version | A numeric revision of a public contract, matched exactly | Separate from a package release version; no inferred semver compatibility |
| Operation | A named method in a capability contract, with input and return schemas | It can be called directly without an action wrapper |
| Invocation request | One call containing its imported capability/operation or action descriptor, business input and execution metadata | Separate from a reusable declaration, selected provider binding or broadcast result |
| Action descriptor | The public, versioned contract for an invocable use case, created by defineActionContract |
Safe for clients to import without its handler |
| Action contribution | A packaged handler created by defineAction, implementing an action descriptor with execution assignment and capability requirements |
May compose several operations; does not replace capabilities |
| Contribution | An addition supplied by a plugin, such as a service, action, view, transform or script | Shared terminology and ownership rules, not a mandatory mixed array |
| Contribution kind | The category determining a contribution's declaration shape and activation behavior | Built-in kinds have dedicated plugin properties |
| Extension contribution | A declaration carrying an imported custom-kind descriptor and a validated payload | Extends the model without arbitrary plugin keys or a closed kind switch |
| Service definition | An inert recipe created by defineService, implementing a mandatory capability contract |
The same recipe type is used for startup and runtime installation |
| Plugin | A named composition of contribution definitions installed and controlled together | Neither a browser extension nor a provider; its contributions can fail independently |
| Definition helper | A function preserving declaration types and checking declarative invariants | Does not install a service, register a listener or start a runtime |
Use native APIs and types directly when their semantics fit. Similar words do not imply identical contracts:
| SDK term | Native Devframe concept | Boundary |
|---|---|---|
| Service definition | Local services.provide or a package-based wire-service definition |
The SDK adds exact capability contracts and owned dependency/replacement lifecycle. Native wire-service identity/version is npm package/semver. |
| Plugin | Native host plugin/definition | An SDK plugin groups owned contributions. It can be installed by a native plugin; it does not replace host plugin setup. |
| Client | Native RPC/client context | The SDK client selects among provider connections. Each connection retains native transport, authentication and serialization. |
| Shared state | Native SharedState and host state publication |
Preserve native lifetime and writes. Contributions/hosts own keys, scope, validation, persistence and conflicts. |
| View contribution | Native view publication and subscriptions | The SDK owns the setup recipe's activation scope; the author registers native cleanup explicitly. |
| Script contribution | Native script registration or a native HTML-hook recipe | The SDK owns registration setup and cleanup; native tooling packages executable code and native hosts own timing, permissions and world semantics. |
| Published view/renderer | Native JSON-render model, refs and hub mount/dispose | Reuse native publication, discovery and rendering. The host owns UI placement. |
See the upstream alignment review for the source comparison and remaining gaps.
| Term | Definition | Distinction |
|---|---|---|
| Host | The application composing providers, clients, adapters and policy | Can use several realms and providers concurrently |
| Provider | An identifiable owner offering contracts and operation execution in a realm | Multiple providers can offer the same capability |
| Provider ID | A stable logical identity configured by the embedding host for a provider | Preserves selection across backend recreation; does not authenticate an endpoint |
| Provider incarnation | An opaque identity for one lifetime of that provider's backend runtime | Pins operation ownership. Changing it does not reset state owned by a surviving native host. |
| Discovery registry | The client composition root's owned collection of provider connections and their advertised metadata | Coordinates discovery for consumers; does not merge provider state or create another RPC engine |
| Realm | An extensible environment family, initially webext or devserver |
Devframe and Vite are integrations within a realm, not mutually exclusive realm families |
| Provider runtime | The role responsible for admission, activation and authoritative operation execution | May integrate into an existing native host rather than require a new runtime constructor |
| Client runtime | The role responsible for discovery, selection, subscriptions, calls and presentation bindings | May run without owning the provider's native resources |
| Execution context | The actual process, worker or document where code and native resources belong | Distinct from provider identity, realm and UI placement |
| Execution agent | Target-scoped code performing delegated work for a provider in another execution | A content/page script does not automatically become an independently trusted provider |
| Adapter | Code integrating portable contracts with an environment's lifecycle, resources and communication | Broader than a transport; server adapters reuse existing Devframe/Vite machinery |
| Transport | The channel carrying protocol messages | Does not by itself implement capabilities or render UI |
| Native context | The actual environment/library resources owned by a local execution | Remote metadata cannot contain native handles |
| Native context descriptor | An imported key associating a local context resource with its type | Presence is checked separately from a realm label |
| Term | Definition | Distinction |
|---|---|---|
| Admission batch | Definitions inspected together before any setup in that batch runs | Strict admission failure rejects the entire batch, preserving earlier installations |
| Registration | An admitted, owned declaration in a provider registry | Admission does not guarantee successful or currently eligible activation |
| Service slot | A provider's registration identity for one capability ID and exact contract version | Different versions can coexist; repeated references to the same definition still conflict |
| Installation handle | A local control and observation object for one admitted service or plugin installation | Not a service API and not a shared ownership lease |
| Activation | One live generation of a contribution's executable registrations and owned resources | Capability restoration can create a new generation without reinstalling its declaration |
| Activation scope | The owner of resources created during one activation | Ends before a replacement activation can begin |
| Capability binding | A consumer's typed API and context for a resolved provider implementation | Gives access, not installation ownership or permanent availability |
| Requirement | A declared capability dependency that must be bound before activation | Does not grant permissions or route different dependencies implicitly to different providers |
| Availability | Whether a contract is currently ready in the relevant execution | Separate from whether a particular request applies to a domain/resource |
| Setup failure | Failure while activating an admitted declaration | Isolated from independent contributions; requires explicit retry |
| Cleanup blocked | A lifecycle condition where the old activation has not been proven ended | Prevents replacement until cleanup or verified execution reset succeeds |
| Replacement | Explicitly ending an old installation/activation before admitting or activating its successor | Ordinary duplicate registration is never replacement |
| Host-managed reload | Updating or restarting through the existing host's supported module/server lifecycle | Adapter cleanup remains necessary; a Vite server restart does not terminate its Node process |
| Term | Definition | Distinction |
|---|---|---|
| Resource / target | A subject defined by a capability, such as a domain, document or debugger session | Its identity and freshness rules belong to that capability, with no universal SDK shape |
| Invocation | One requested operation call with schema-defined input, cancellation and routing context | Resource identifiers and filters are ordinary typed input |
| Routing policy | Rules selecting eligible providers before dispatch | Distinct from service construction and provider-state synchronization |
| Applicability | Whether a request concerns resources owned by an implementation | Implementation code and schema-defined results; not provider readiness or authorization |
| Command result | The typed value or error returned to the initiating caller | Other clients observe state separately; no implicit event bus or automatic replay |
| Ambiguous selection | More than one equally eligible provider satisfies the current selector | Requires an explicit caller/UI/agent discriminant; discovery order cannot pick a winner |
| Dispatch | The routing boundary after which an invocation's selected route cannot change | A timeout or reported failure does not authorize fallback or replay |
| Broadcast | Explicit execution across several selected providers with individual outcomes | Does not merge provider state or replace ordinary value-returning methods |
| Diagnostic | A serializable report identifying a failure's code, owner and phase | Native exceptions remain local; diagnostics support logs and current/later UI |
| View contribution | An inert setup recipe created by defineView, with execution assignment and optional capability requirements |
Owns native publication and subscriptions through its activation scope; it is not the published view |
| Published view | The native JSON presentation exposed through a native view handle, shared state and index | Its renderer and surface lifetime remain host-owned; referenced actions are not implicit activation requirements |
| Renderer | An implementation turning the JSON view contract into UI | Replaceable; its own framework does not become a dependency of authoring contracts |
| Action binding | Client-local association between an imported action contract and its dispatch policy | Connects native JSON action IDs to the router; does not install handlers or own providers |
| UI surface | Where a view is mounted, such as popup, options, panel or sidebar | Separate from realm, provider and execution ownership |
| Live preview | Built assets served with a live provider for actions and state | Separate from a static snapshot and from a source development server |
| Relationship | Meaning |
|---|---|
| A provider implements a capability through a service definition | Contract and implementation stay separate |
| A contribution requires capabilities | Typed bindings supply its dependencies |
| A plugin contains contributions | Dedicated properties preserve kind-specific typing |
| A host composes providers and clients | One UI can use a development server or extension provider according to policy |
| An adapter satisfies environment integration | Local native resources remain accessible without leaking across transport |
| A renderer mounts views on surfaces | Presentation lifetimes remain separate from provider work |
An installation result is a direct installation handle under strict admission. Relaxed admission returns an admitted handle envelope or a skipped diagnostic; a skipped definition owns no handle. A handle reports current activation status separately from admission.
A host-owned remote method is a named native RPC entry point for an explicitly exposed contract. Its registration lasts for the host lifetime, independently of contribution implementation availability. Disabling or disposing an implementation makes calls unavailable; the method's presence alone does not establish readiness or authorization.
defineActionContract({ id, version, operation, routing? }) describes a callable action and an optional client-visible route default. defineAction({ contract, id, execution, requires?, handler }) implements it. defineService({ capability, id, execution, requires?, setup }) implements a capability. defineView({ id, execution, requires?, setup }) declares a view contribution in plugin.views; its setup returns Awaitable<void> and registers native resource cleanup through the supplied scope. The owner accepted this recipe on 2026-10-02. defineScript uses the same input and setup contract in plugin.scripts, owning native registration rather than compiling source or executing page callbacks remotely. Script decision. defineTransform uses that setup contract in plugin.transforms, owning native transformation registration. Its host or capability retains stage, ordering and failure behavior. Transform contract. All definition helpers use one object; “contribution” describes their shared ownership model, not a second action API.
A route selector constrains a required string realm and optional string provider. Its provider identity is scoped to that realm. Symbol descriptions and numbers are not normalized into identifiers. The caller owns stable naming; the runtime owns validation and collision detection. A selector identifies a logical provider, while a bound invocation retains one specific incarnation.
A routing directive is a selector or a non-empty ordered list of selectors for one invocation. The list describes fallback before dispatch, not broadcast. An explicit per-call directive replaces the action contract's default. Core exports this declarative portion as RouteSelector and RoutingDirective. A routing policy is a directive or local RoutingCallback; @devkit/client executes it. A per-call policy replaces the action default, which replaces the client default.
A provider catalog describes the action and capability contracts registered in one provider, including exact contract versions, execution and lifecycle status. The local catalog is authoritative immediately. A connection adapter must distinguish an unsynchronized remote catalog from a confirmed empty one. Catalog membership or active status does not grant permission or authorize a target.
An asynchronous routing callback selects from its original candidate owners and rechecks their current readiness. If the selected provider's incarnation changes before dispatch, the invocation fails as stale; a fresh invocation may select the successor. Broadcast requires a separate selection field whose selectors form a union of recipients. It does not inherit ordinary routing defaults.
A provider connection is an adapter-owned authenticated connection with fixed provider identity, observable catalog and invocation methods. A provider attachment is the client's ownership of that connection in its registry; detaching it cancels client work without disposing the backend. For native remote unary RPC, cancellation stops the caller waiting; already-dispatched backend work may finish. No automatic retry or replay follows.
A surface can own several provider connections. Losing one transport does not end the others; explicit surface disposal ends all connections that surface owns.
An unmatched broadcast selector names no known provider. The entire broadcast rejects before dispatch and lists these selectors. A known provider that is currently unavailable remains a recipient and receives its own rejected outcome.