I don’t know the Apps at all well, but what you have there looks very wrong to me.
I think you need to treat the battery much as a second Grid connection. The Power3 (Batt) process list looks OK in itself - but for reasons I’ll explain below, you might need to move at least some of the other processing into there too.
What alarmed me was you are writing to emontx3:use (power) and emontx3:use_kwh (energy) from both power1 and power2. You can’t do that. Think of the Feed as boxes on a conveyor going past, one every 10 seconds. The second value to land in the box overwrites the first, and the first one is lost.
You need to rethink your processes in terms of all three inputs being processed sequentially; i.e. all the steps relating to CT1 get processed - and all the values calculated there become available for use in CT2’s process list, and when you do CT3’s process list, all the values from CT1 & CT2 are available. The catch is, the values for CTs 2 & 3 are available to CT1 processes but they are 10 seconds old. Beware. In step 3 of power1, that’s exactly what is happening with power2 input - it is old data. It is likely to show up as unexplained spikes on the graphs.
So what I recommend is, do all the adding and subtracting in the last list where a quantity you’re using in the maths has already been read (and probably logged to a feed).
For subtle reasons linked to this timing problem, it is also recommended you use the value of the Feed rather than the Input when fetching the number to add or subtract it.
If Grid import, Solar generation and Battery discharge are all positive numbers, then it looks to me as if Grid positive + Battery positive + Solar positive = use and this fits the description in MySolarBattery.
I think when you have sorted this out, what to allocate in MySolarBattery will be relatively straightforward. Solar, battery_charge and battery_discharge are clear, I presume battery_soc = battery_charge×efficiency - battery_discharge if it’s not available to you any other way, and might need tweaking in the light of experience; and I think solar_direct should be what you interpret it to mean - probably solar that does not contribute to battery charging and is not exported.
And yes, I’d support your call for proper documentation for all the Apps.