failed balance assertion explanation could include a breakdown of subaccounts when ==* is used

[lestephane]

My understanding is that ==* is very useful to check that virtual / transfer accounts are all zero at the end of the month, or beginning of the year. I call those accounts zerosum accounts.

2021-02-01 Zerosum accounts start the month empty
    ; generated-transaction: ~ monthly from 2021-01-01 to 2022-01-01
    ...
    Transfers                                                     0 ==* 0 EUR
    Transfers                                                     0 ==* 0 USD
    Transfers                                                     0 ==* 0 GBP
    nothing

assertion details:
date:       2021-02-01
account:    Transfers (and subs)
commodity:  EUR
calculated: -22.30000000
asserted:   0
difference: 22.30000000

Then I need to figure out which of the sub-accounts contributed to the assertion failure .

Putting the breakdown of those non-zero subaccount balances would save time.

I started using ==* only this month, and realized how many of my transfers account were non-zero (a typical sign of bugs in my own hledger-flow import scripts). It even found some EUR in subaccounts that were actually named with USD at the end.

Workaround (Edit 2021-04-21)

To find out the culprit(s) (in this example)

hledger bal -I --end 2018-04-02 Transfers: cur:EUR

notice the date is the date from the assertion details + 1 day

(Edit 2021-04-22)

Use reg and slide the date forwards to discover whether the situation 'corrects' itself in time.

hledger reg -I --end 2018-04-15 Transfers: cur:EUR

If not, it's a bug (ie, the journal contains money in a transitory transfer account that is only put in, and
never taken out, or vice versa). If it does correct itself, consider changing the date of that assertions to another
day where there is less noise. Most of the time, the failure will not be a bug, but a transfer that
was still ongoing at the time the balance_assertion is checked (left the source account, but did
not arrive yet in the destination account).

[simonmichael]

Maybe you could draft some mockups/examples ?

[lestephane]

Having this:

$ hledger bal Transfers: -I --end 2018-04-02 --empty
                   0  Transfers:DKB:Personal:EUR
                   0  Transfers:Forex
          7,0400 EUR  Transfers:PayPal
                   0  Transfers:Relai
                   0  Transfers:TransferWise:Business-CY:EUR
                   0  Transfers:TransferWise:Business-CY:USD
                   0  Transfers:TransferWise:Personal:EUR
                   0  Transfers:TransferWise:Personal:USD
--------------------
          7,0400 EUR  

And an assertion failure failing like this

2018-04-01 Zerosum accounts start the month empty  ; applied-autoposting:recurring.checks.topups.2018.zerosum_monthly
    Transfers:Forex                                               0 ==* 0 EUR  ; check:zerosum
    Transfers:Forex                                               0 ==* 0 GBP  ; check:zerosum
    Transfers:Forex                                               0 ==* 0 USD  ; check:zerosum
    Transfers:Forex                                               0 ==* 0 XBT  ; check:zerosum
    Transfers:Relai                                               0 ==* 0 EUR  ; check:zerosum
    Transfers:Relai                                               0 ==* 0 XBT  ; check:zerosum
    Transfers:TransferWise:Personal:EUR                           0 ==* 0 EUR  ; check:zerosum
    Transfers:TransferWise:Personal:USD                           0 ==* 0 USD  ; check:zerosum
    Transfers:TransferWise:Business-CY:EUR                        0 ==* 0 USD  ; check:zerosum
    Transfers:TransferWise:Business-CY:USD                        0 ==* 0 USD  ; check:zerosum
    Transfers                                                     0 ==* 0 EUR  ; check:zerosum
    Transfers                                                     0 ==* 0 USD  ; check:zerosum
    Transfers                                                     0 ==* 0 GBP  ; check:zerosum
    Transfers                                                     0 ==* 0 XBT  ; check:zerosum
    Equity:Opening Balances                                       0

assertion details:
date:       2018-04-01
account:    Transfers (and subs)
commodity:  EUR
calculated: 7.04
asserted:   0
difference: -7.04

You could either indent each offending account below the account field in the assertion details

assertion details:
date:       2018-04-01
account:    Transfers (and subs)
  \-Transfers:PayPal  7,0400 EUR
  ...
commodity:  EUR
calculated: 7.04
asserted:   0
difference: -7.04

Or indent each offending account below the position containing the balance assertion

2018-04-01 Zerosum accounts start the month empty  ; applied-autoposting:recurring.checks.topups.2018.zerosum_monthly
    ...
    Transfers                                                     0 ==* 0 EUR  ; check:zerosum
      \- Transfers:PayPal  7,0400 EUR

[lestephane]

I'm not clear whether two subaccounts cancelling each other out, say,

Transfers:PayPal  7,0400 EUR
Transfers:CashApp  -7,0400 EUR

Would trigger the balance assertion at the level of the parent currently.

I think they each in isolation violate the parent assertion, and should therefore both be listed.

  | - Transfers:PayPal  7,0400 EUR 
  \ - Transfers:CashApp  -7,0400 EUR

[simonmichael]

To make this still more concrete, if you have time you could make an example or two, including the minimal journal and the desired output.

[simonmichael]

PS it does sound like a useful feature, if these thought experiments show no big problem.

[simonmichael]

If the two subaccounts cancel each other out, the parent account's assertion is satisfied, so it should pass (and does). If you want to ensure each subaccount is zero, you have to assert for each of them.

With subaccount-including assertions, it's possible to have more than one assertion failing at once. Generally hledger only reports a single error, the first one it hits. Reporting multiple failing subaccount assertions at once might be a bit inconsistent, though if it provides significant value in practice, it could be worth it.

Whether reporting one or many assertion errors, I think your idea of possibly showing them inline in the displayed journal entry is a good one.

[lestephane]

So it's going to be taking some time (again), because command line accounting for the month of march is still ongoing here. I'm 3 weeks late delivering my records to the accountant. I don't know how you manage this project and have time left to do billable work!

[simonmichael]

It has always been difficult and is getting more so...

[lestephane]

Mockups

"╚╝╬═╩╠╣╦╔╗║" from https://social.technet.microsoft.com/wiki/contents/articles/20557.visual-basic-how-to-draw-a-border-of-ascii-text-in-a-console-application.aspx

Scenario 1: one assertion per currency

(which is the only way hledger supports today)

Input

commodity 9.999,99 EUR
commodity 9,999.99 USD
commodity 9,999.99999999 XBT

2021-01-01 * "opening balances"
    Equity:Opening-Balances
    Transfers:Personal:Revolut:EUR             1,11 EUR
    Transfers:Business:Revolut:EUR            -2,22 EUR
    Transfers:Personal:WiseDotCom:USD         -3.33 USD
    Transfers:Business:WiseDotCom:USD          4.44 USD
    Transfers:Personal:Coinbase                0.00555555 XBT
    Transfers:Business:Coinbase               -0.00666666 XBT

2021-05-01 * "monthly assertions"
    Assertions
    Transfers                                  0 ==* 0 EUR
    Transfers                                  0 ==* 0 USD
    Transfers                                  0 ==* 0 XBT

Result

$ hledger bal  -f input-transactions.journal 
hledger-39623934c38e12007434aeb4bf6fc0a280b62889: balance assertion: "/home/lestephane/Vault/Finance/input-transactions.journal" (line 13, column 50)
transaction:

2021-05-01 * "monthly assertions"
    Assertions               0
    Transfers                0 ==* 0 EUR
      ╔═════════════════════════════════════════════════════╗
      ║Transfers:Personal:Revolut:EUR               1,11 EUR║
      ║Transfers:Business:Revolut:EUR              -2,22 EUR║
      ╠═════════════════════════════════════════════════════╣
      ╚Total                                       -1,11 EUR╝
    Transfers                0 ==* 0 USD
    Transfers                0 ==* 0 XBT

assertion details:
date:       2021-05-01
account:    Transfers (and subs)
commodity:  EUR
calculated: 1.11
asserted:   0
difference: -1.11

Scenario 2: one multi currency assertion

Input

commodity 9.999,99 EUR
commodity 9,999.99 USD
commodity 9,999.99999999 XBT

2021-01-01 * "opening balances"
    Equity:Opening-Balances
    Transfers:Personal:Revolut:EUR             1,11 EUR
    Transfers:Business:Revolut:EUR            -2,22 EUR
    Transfers:Personal:WiseDotCom:USD         -3.33 USD
    Transfers:Business:WiseDotCom:USD          4.44 USD
    Transfers:Personal:Coinbase                0.00555555 XBT
    Transfers:Business:Coinbase               -0.00666666 XBT

2021-05-01 * "monthly assertions"
    Assertions
    Transfers                                  0 ==* 0 EUR,USD,XBT

Result

$ hledger bal  -f input-transactions.journal 
hledger-39623934c38e12007434aeb4bf6fc0a280b62889: balance assertion: "/home/lestephane/Vault/Finance/input-transactions.journal" (line 13, column 50)
transaction:

2021-05-01 * "monthly assertions"
    Assertions               0
    Transfers                0 ==* 0 EUR
      ╔═════════════════════════════════════════════════════╗
      ║Transfers:Personal:Revolut:EUR               1,11 EUR║
      ║Transfers:Business:Revolut:EUR              -2,22 EUR║
      ╠═════════════════════════════════════════════════════╣
      ╚Total                                       -1,11 EUR╝
    Transfers                0 ==* 0 USD
      ╔═════════════════════════════════════════════════════╗
      ║Transfers:Personal:WiseDotCom:USD           -3.33 USD║
      ║Transfers:Business:WiseDotCom:USD            4.44 USD║
      ╠═════════════════════════════════════════════════════╣
      ╚Total                                        1.11 USD╝
    Transfers                0 ==* 0 XBT
      ╔═════════════════════════════════════════════════════╗
      ║Transfers:Personal:Coinbase            0.00555555 XBT║
      ║Transfers:Business:Coinbase           -0.00666666 XBT║
      ╠═════════════════════════════════════════════════════╣
      ╚Total                                 -0.00111111 XBT╝


assertion details:
date:       2021-05-01
account:    Transfers (and subs)
commodity:  (multiple)
calculated: (see breakdown)
asserted:   0
difference: (see breakdown)