The edge case is only related to building vehicles, I'm not sure what note I could put on IsValidVehicle without being overly specific - it's not a valid vehicle because the vehicle doesn't exist any more.

This rather looks like a bug that should be fixed, instead of being documented.
In the API "VehicleId" refers to a wagon chain, i.e. always to the first vehicle in a chain.
BuildVehicle should always create a new chain.
If it does not do that for wagons, it's a bug.

The intention of the API is that OpenTTD should never attach wagons automatically, to make stuff easy/predictable for the AI.

I'm tempted to agree, but writing a compatibility shim for that could be tricky...

SimpleAI and WormAI make active use of this behaviour (same "railbuilder.nut" in both AIs).
They build N pax wagons, N mail wagons, remember only the first ID, refit the chains and then attach the chains to the engine.
It also does some magic shuffling, if it turns out that pax and mail wagons are the same wagons.

Looking at the available API functions, there's no way to find the vehicles in a particular depot - you'd need to iterate through all vehicles and check state (is in depot) & location. Would turn BuildVehicle into a very expensive function. Not actually sure what you'd do to check whether a vehicle is just an unattached wagon

So yes, fixing this "bug" and adding a compatibility shim would be possible, but would really require adding a couple new API functions. Worth it?

Sounds like a big API change, but big changes only work if someone uses them.
So documenting this is the best option until there is actual demand by AI authors for a better API. But it seems they were happy working around the weirdness.