@callback all_impl_models() :: {:ok, [Spex.ImplModel.t()]}

Returns all currently known implementation models.

@callback all_instances() ::
  {:ok, [Spex.InstanceManager.Instance.t()]}
  | {:error, Spex.Errors.DetsError.t()}

Returns all instances managed by this instance manager.

@callback all_instances(Spex.Specification.t()) ::
  {:ok, [Spex.InstanceManager.Instance.t()]}
  | {:error, Spex.Errors.DetsError.t()}

Returns all instances for a given specification module.

@callback child_spec(term()) :: Supervisor.child_spec()

Returns a child spec for supervising the instance manager.

@callback delete_instance(Spex.InstanceManager.Instance.instance_identifier()) ::
  :ok | {:error, Spex.Errors.DetsError.t()}

Deletes one instance by identifier.

@callback delete_instances((Spex.InstanceManager.Instance.t() -> as_boolean(term()))) ::
  :ok | {:error, Spex.Errors.DetsError.t()}

Deletes all instances matching the provided filter function.

@callback export_impl_models() ::
  {:ok, [{filename :: String.t(), Spex.ImplModel.serialisation()}]}

Serialises and exports implementation models as {filename, content} tuples.

@callback get_instance(Spex.InstanceManager.Instance.instance_identifier()) ::
  {:ok, Spex.InstanceManager.Instance.t()}
  | {:error, Spex.Errors.InstanceError.t()}
  | {:error, Spex.Errors.DetsError.t()}

Fetches one instance by identifier.

@callback init_instance(
  Spex.Specification.t(),
  Spex.InstanceManager.Instance.instance_identifier(),
  Spex.InstanceManager.Instance.meta() | nil,
  Spex.state() | nil
) :: :ok | Spex.Specification.error_handler_return()

Initializes a new instance and records initialisation as the first transition.

Returns :ok on success or an error-handler return when initialization fails.

@callback init_instance!(
  Spex.Specification.t(),
  Spex.InstanceManager.Instance.instance_identifier(),
  Spex.InstanceManager.Instance.meta() | nil,
  Spex.state() | nil
) :: :ok

Same as init_instance/4, but raises on errors.

@callback init_instance_async(
  Spex.Specification.t(),
  Spex.InstanceManager.Instance.instance_identifier(),
  Spex.InstanceManager.Instance.meta() | nil,
  Spex.state() | nil
) :: :ok

Asynchronously initializes a new instance.

Errors are reported via specification error handling instead of direct return.

@callback mock_instance!(
  Spex.Specification.t(),
  Spex.InstanceManager.Instance.instance_identifier(),
  Spex.state(),
  Spex.InstanceManager.Instance.meta() | nil
) :: :ok

Inserts or updates a mock instance at a given state for testing purposes.

@callback start_link([instance_manager_opt()]) :: Supervisor.on_start()

Starts the instance manager process tree.

@callback transition(
  Spex.InstanceManager.Instance.instance_identifier(),
  Spex.action(),
  Spex.state()
) :: :ok | Spex.Specification.error_handler_return()

Records an observed transition for an existing instance.

Returns :ok on success or an error-handler return when validation/storage fails.

@callback transition!(
  Spex.InstanceManager.Instance.instance_identifier(),
  Spex.action(),
  Spex.state()
) :: :ok

Same as transition/3, but raises on errors.

@callback transition_async(
  Spex.InstanceManager.Instance.instance_identifier(),
  Spex.action(),
  Spex.state()
) :: :ok

Asynchronously records a transition for an existing instance.