Thank you for the explanation about streams.

My first observation is that the details clarified in this conversation
are easily understood from the man page, nor from any official online
documentation I had found, nor even from any other discussion or
documentation I had found through web searches. Thus, even if it were
the only change to result from these considerations, I would suggest
that the man page should include a more robust explanation of the
design.

Next, the child stream being restored to a new subvolume, with the
result sharing references with the parent, may be practical from a
standpoint of underlying implementation, but may not be intuitive for a
user in a typical work flow. It might be helpful for users to have some
direct support for the use case of updating an existing stream in
place.

Finally, the constraint that a restore target must have the same file
name as the original subvolume is, at least to my thinking,
inconvenient, if not also in many cases challenging, as when the
original name is not known, perhaps having been chosen arbitrarily. A
useful feature would be an option in the administrative tool to choose
the name of the restored subvolume, not simply the parent directory.

Whether any such enhancements require changes to the file system
functionality is beyond my knowledge, but it is certainly worthwhile to
consider any that are possible through changing only tools in user
space.