The notification can be done by sending some data to $NOTIFY_SOCKET. That's all sd_notify does.

Notice that the protocol specification is way more complex than that, and already changed since systemd was released.

All the library does is sending some data through the socket, but that's not at all what the docs tell you to do.

The docs could be better, sure, but where did this idea what "interfaces can never be changed" come from?

It comes from the idea that your computer shouldn't stop working at random.

But surely, what is needed is "interfaces can never be changed without redefining your project in a way that makes absolutely obvious it's incompatible with its past". Systemd fails that one too.

Even more, why can't information like this be passed up the call chain as integer return codes? That scheme has been a perfectly functional for decades, all the way back to at least BSD's rc scripts, maybe before.