@spec cleanup() :: :ok

Cleans up all plugin states.

@spec get_plugin_metadata(plugin_id()) :: {:ok, map()} | {:error, :not_found}

Gets plugin metadata.

@spec get_plugin_state(plugin_id()) :: {:ok, plugin_state()} | {:error, :not_found}

Gets plugin state by plugin ID.

@spec initialize(term()) :: {:ok, term()}

Initializes the plugin state manager subsystem.

@spec initialize_plugin_state(plugin_module(), plugin_config()) ::
  {:ok, plugin_state()}

Initializes plugin state for a given plugin module.

Creates initial state based on the plugin's configuration and stores it in the unified state management system under the plugins namespace.

@spec list_plugin_states() :: [{plugin_id(), plugin_state()}]

Lists all plugin states.

@spec remove_plugin(plugin_id()) :: :ok

Removes plugin state and metadata.

@spec set_plugin_state(plugin_id(), plugin_state()) :: :ok

Sets plugin state directly.

@spec update_plugin_state(plugin_id(), (plugin_state() -> plugin_state())) ::
  {:ok, plugin_state()}

Updates plugin state using an update function.

@spec update_plugin_state_legacy(plugin_id(), plugin_state(), plugin_config()) ::
  {:ok, plugin_state()}

Updates plugin state using legacy interface for backward compatibility.

Maintains state in the unified state manager and supports both functional and imperative update patterns.