Agreed, multiple shadow CIBs aren't invalid, also not what I said, just that invalid configurations are possible and that we shouldn't try to foolproof everything, that's all. If the current implementation allows multiple CIBs, and allows you to make a CIB, add cs_* resources, commit it, and do it all over with different resources on a different CIB within the same Puppet run, then you're correct and this change is incompatible. But I'm not entirely sure it worked, never tried the original implementation with multiple shadow CIBs, didn't see the use case for it at all and configuring it in Puppet will even more likely be absolute hell. If you did however, a simple array to keep track of which CIBs you already initialized could easily solve this.

About documentation: didn't update them, but then again, it also didn't exist. My changes work for me, and I'm committing it upstream so other people can enjoy the fruits of my labor. If you have different use cases, feel free to submit a patch.