## Adapter


Structural contract for a device plugin adapter.


Usage

``` python
Adapter()
```


A plugin exposes a no-argument `create_plugin()` factory (named by the descriptor's `integration.adapter.entry_point`) returning an adapter, which the host drives through a strict lifecycle: [open](Adapter.md#benchweave_sdk.Adapter.open) binds descriptor and services, [execute](Adapter.md#benchweave_sdk.Adapter.execute) runs one operation, [next_event](Adapter.md#benchweave_sdk.Adapter.next_event) polls a subscription, and [close](Adapter.md#benchweave_sdk.Adapter.close) releases the session. Construction and [open](Adapter.md#benchweave_sdk.Adapter.open) stay free of device I/O; each session uses a fresh adapter instance.


## Examples

A minimal read-only adapter skeleton:

``` python
class DemoAdapter:
    async def open(self, descriptor, services, context): ...
    async def execute(self, request, context): ...
    async def next_event(self, subscription_id, context): ...
    async def close(self, context): ...
```


## See Also

[HostServices](HostServices.md#benchweave_sdk.HostServices)  
scoped services handed over at open.

[OperationContext](OperationContext.md#benchweave_sdk.OperationContext)  
identity, deadline, and cancellation per operation.


## Methods

| Name | Description |
|----|----|
| [close()](#close) | Release the adapter session; tolerate repeated calls. |
| [execute()](#execute) | Run one operation and return its result envelope. |
| [next_event()](#next_event) | Return the next pending event for a subscription, or None. |
| [open()](#open) | Bind the adapter to its descriptor and scoped host services. |

------------------------------------------------------------------------


#### close()


Release the adapter session; tolerate repeated calls.


Usage

``` python
close(context)
```


------------------------------------------------------------------------


#### execute()


Run one operation and return its result envelope.


Usage

``` python
execute(request, context)
```


Implementations call `context.mark_dispatch_started()` immediately before the first transmit, honour the context deadline and cancellation, never retry silently, and preserve uncertain outcomes: a failure after dispatch is reported with status `"unknown"` rather than `"error"`.


##### Parameters


`request: dict[str, Any]`  
Operation envelope with exactly `operation_id`, `verb` and `arguments`.

`context: OperationContext`  
Identity, deadline, and cancellation state for the operation.


##### Returns


`dict`  
Result envelope: `operation_id`, `verb`, `status` (`"ok"`, `"error"` or `"unknown"`) and either `data` or an `error` object carrying `code`, `message` and `dispatch_state`.


------------------------------------------------------------------------


#### next_event()


Return the next pending event for a subscription, or None.


Usage

``` python
next_event(subscription_id, context)
```


------------------------------------------------------------------------


#### open()


Bind the adapter to its descriptor and scoped host services.


Usage

``` python
open(descriptor, services, context)
```


Called once per session before any other method. Implementations keep construction and [open](Adapter.md#benchweave_sdk.Adapter.open) free of device I/O and defer all transport to the supplied `services`.


##### Parameters


`descriptor: dict[str, Any]`  
The plugin's validated device descriptor.

`services: HostServices`  
Scoped host services for transport, clocks, and evidence.

`context: OperationContext`  
Context for the open operation itself.