@callback add_shape(stack_ref(), Electric.Shapes.Shape.t()) ::
  {:ok, shape_handle()} | {:error, term()}

@callback consume_shape_storage_state(stack_ref(), shape_handle()) :: term() | nil

@callback count_shapes(stack_ref()) :: non_neg_integer()

@callback fetch_shape_by_handle(stack_ref(), shape_handle()) ::
  {:ok, Electric.Shapes.Shape.t()} | :error

@callback get_existing_shape(stack_ref(), Electric.Shapes.Shape.t() | shape_handle()) ::
  {shape_handle(), Electric.Replication.LogOffset.t()} | nil

@callback initialise_shape(
  stack_ref(),
  shape_handle(),
  xmin(),
  Electric.Replication.LogOffset.t()
) :: :ok

@callback initialize_from_storage(stack_ref(), Electric.ShapeCache.Storage.storage()) ::
  :ok | {:error, term()}

@callback list_shapes(stack_ref()) :: [{shape_handle(), Electric.Shapes.Shape.t()}]

@callback mark_snapshot_started(stack_ref(), shape_handle()) :: :ok

@callback remove_shape(stack_ref(), shape_handle()) ::
  {:ok, Electric.Shapes.Shape.t()} | {:error, term()}

@callback reset(stack_ref()) :: :ok

@callback set_latest_offset(
  stack_ref(),
  shape_handle(),
  Electric.Replication.LogOffset.t()
) :: :ok

@callback set_shape_storage_state(stack_ref(), shape_handle(), term()) :: :ok

@callback set_snapshot_xmin(stack_ref(), shape_handle(), xmin()) :: :ok

@callback shape_last_used_table(stack_ref()) :: atom()

@callback shape_meta_table(stack_ref()) :: atom()

@callback snapshot_started?(stack_ref(), shape_handle()) :: boolean()

@callback terminate(stack_ref(), String.t()) :: :ok | {:error, term()}