imp: add: Verify balance assertions on each posting (#2355)

[reesmichael1]

As requested in #2355, this verifies balance assertions during hledger add. Here's an example of the new workflow. With the following journal file:

2025-03-18 * Deposit
    Assets:Checking                     $20
    Income:Salary                      $-20

$ hledger add
Date [2025-03-19]:
Description: Food
Account 1: Expenses:Food
Amount  1: $15
Account 2: Assets:Checking
Amount  2 [$-15]: $-15 == $10
1:6:
  | 2025-03-19 Food
  |     Expenses:Food               $15
3 |     Assets:Checking            $-15 == $10
  |                                     ^^^^^^
  |                                  $0

Balance assertion failed in Assets:Checking
Across all commodities at this point, excluding subaccounts, ignoring costs,
the asserted balance is:        $10
but the calculated balance is:   $5
(difference: $5)
To troubleshoot, check this account's running balance with assertions disabled, eg:
hledger reg -I 'Assets:Checking$'
Amount  2 [$-15]: $-15  == $5
Account 3 (or . or enter to finish this transaction):
2025-03-19 Food
    Expenses:Food               $15
    Assets:Checking            $-15 == $5

Save this transaction to the journal ? [y]: y
Saved.

The only thing that might be odd here is including the "To troubleshoot..." lines. I left those in because it's not bad advice for tracking down why an assertion might be failing, but also it isn't really helpful and might be misleading in the middle of an hledger add, so I'm open to removing those lines here.

[simonmichael]

Thanks for this!

We should try to explore and document how this differs from the behaviour of balance assertions when reading a journal. I think it must be at least a little different, if immediate feedback is desirable (and I agree that it is).

Here are some things to check:

• assertion types: do =, ==, =*, ==* all work ?
• balance assignments: what happens if someone tries to write a balance assignment (omitting the posting amount) ?
• multiple assertions in one transaction
• multiple assertions to the same account within one transaction
• posting dates (I think hledger add supports those), which could allow entering multiple assertions to the same account in non date order

[reesmichael1]

Sorry for letting this languish for a bit! Some other projects have consumed me. I'm happy to review/document all of this, and will try to do it later this week or early next week.

[reesmichael1]

(Let's ignore that it's taken me three weeks to resurface....)

Doing all of this definitely revealed some bugs! I'll explore fixing them, just wanted to get them documented first:

• = and =* work as expected unless the transaction being entered is on the same day as other transactions with the same account
• == and ==* also don't work when there are multiple commodities on the right hand side of the assertion (they're not recognized as a valid hledger amount)
• Multiple assertions seem to be fine
• I'll explore posting dates more once the date issues mentioned above are resolved

[simonmichael]

Thanks for the update -

• == and ==* also don't work when there are multiple commodities on the right hand side of the assertion (they're not recognized as a valid hledger amount)

I think we can usually ignore that case - there's no way to write it in journal format. (Explicitly written posting amounts are always single-commodity.)

Re posting dates etc, we like to be flexible but we can impose restrictions for sanity, if needed.