Trait Plugin 

pub trait Plugin: Send {
    // Required methods
    fn init(
        &self,
        assembly_bytes: &[u8],
        assets: &[PuzzleAsset],
        params: &HashMap<String, ParamValue>,
    ) -> Result<(u64, Vec<u8>)>;
    fn register(&self) -> Result<PluginRegistration>;
    fn update_assembly(
        &self,
        session: u64,
        payload: AssemblyPayload<'_>,
        from_gen: u64,
        to_gen: u64,
    ) -> Result<()>;
    fn drop_session(&self, session: u64) -> Result<()>;

    // Provided methods
    fn invoke(
        &self,
        _session: u64,
        _op: &str,
        _ctx: &DispatchContext,
        _params: &HashMap<String, ParamValue>,
    ) -> Result<Vec<u8>> { ... }
    fn start_stream(
        &self,
        _session: u64,
        _op: &str,
        _ctx: &DispatchContext,
        _params: &HashMap<String, ParamValue>,
        _request_id: u64,
    ) -> Result<()> { ... }
    fn poll_stream(&self, _request_id: u64) -> Result<PollOutcome> { ... }
    fn update_stream(
        &self,
        _request_id: u64,
        _params: &HashMap<String, ParamValue>,
    ) -> Result<()> { ... }
    fn cancel_stream(&self, _request_id: u64) -> Result<()> { ... }
    fn query(
        &self,
        _session: u64,
        _query: &str,
        _ctx: &DispatchContext,
        _params: &HashMap<String, ParamValue>,
        _assembly: &[u8],
    ) -> Result<Vec<u8>> { ... }
}

Worker-side plugin interface.

Both Python and native plugins implement this; the host dispatches to it through the C ABI or the in-process boundary.

Concurrency: methods take &self because plugin state mutation is done through interior-mutable host runtimes (Python’s GIL, thread-locked C++ FFI). Plugins MUST be Send so they can be moved between worker startup and the request-loop thread.

Required Methods

fn init( &self, assembly_bytes: &[u8], assets: &[PuzzleAsset], params: &HashMap<String, ParamValue>, ) -> Result<(u64, Vec<u8>)>

Start a session with the given canonical Assembly. Returns the SessionId chosen by the plugin and the assembly bytes of the assembly the plugin actually settled on after any post-Init normalization (full-atom pose build, hydrogen fill, terminal O, etc.). Plugins with no normalization step return an empty Vec<u8>; the host then keeps its input assembly.

assets carries the puzzle asset files delivered at Init (ligand .params/conformer bytes, the electron-density map, etc.), each a (name, data) pair; plugins that don’t consume a given asset ignore it. params is the generic puzzle-config channel (weight-patch + objective-filter entries, plus density resolution/grid-spacing scalars); plugins that don’t consume it ignore it.

Errors

Returns an error if the plugin can’t ingest the assembly or allocate a session.

fn register(&self) -> Result<PluginRegistration>

Return the plugin’s op + query catalog.

Errors

Returns an error if the plugin can’t produce its registration.

fn update_assembly( &self, session: u64, payload: AssemblyPayload<'_>, from_gen: u64, to_gen: u64, ) -> Result<()>

Push an Assembly update to a session. payload carries either a fresh assembly snapshot (Full) or a delta edit list (Delta); from_gen/to_gen are the host’s broadcast generation counters. A plugin whose local gen doesn’t match from_gen should arm a STALE_GEN error to return on its next dispatch so the host re-syncs.

Errors

Returns an error if the payload can’t be applied or the session is unknown.

fn drop_session(&self, session: u64) -> Result<()>

Tear down a session. Idempotent.

Errors

Returns an error if the plugin can’t release the session state.

Provided Methods

fn invoke( &self, _session: u64, _op: &str, _ctx: &DispatchContext, _params: &HashMap<String, ParamValue>, ) -> Result<Vec<u8>>

Single-shot mutating op. Returns the plugin’s working Assembly post-op (assembly bytes); the orchestrator copies locked-entity slices into canonical state.

Errors

Default impl returns PluginError::Unsupported. Implementations return an error on op-level failure.

fn start_stream( &self, _session: u64, _op: &str, _ctx: &DispatchContext, _params: &HashMap<String, ParamValue>, _request_id: u64, ) -> Result<()>

Begin a long-running op under the host-assigned request_id. The plugin keys its stream state on that id.

Errors

Default impl returns PluginError::Unsupported. Implementations return an error if the stream can’t be started.

fn poll_stream(&self, _request_id: u64) -> Result<PollOutcome>

Return the latest snapshot for a running stream.

Errors

Default impl returns PluginError::Unsupported. Op-level failure surfaces as PollOutcome::Error rather than Err.

fn update_stream( &self, _request_id: u64, _params: &HashMap<String, ParamValue>, ) -> Result<()>

Push new params to a running stream.

Errors

Default impl returns PluginError::Unsupported. Implementations return an error if the request id is unknown.

fn cancel_stream(&self, _request_id: u64) -> Result<()>

Stop a running stream. Idempotent.

Errors

Default impl returns PluginError::Unsupported. Implementations return an error if cleanup fails.

fn query( &self, _session: u64, _query: &str, _ctx: &DispatchContext, _params: &HashMap<String, ParamValue>, _assembly: &[u8], ) -> Result<Vec<u8>>

Single-shot read query. Returns query-defined opaque bytes.

assembly (when non-empty) names a specific composition to read/score instead of the session pose; an empty slice means the query operates on the live session / its in-flight snapshot.

Errors

Default impl returns PluginError::Unsupported. Implementations return an error on query failure.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors