easier --forecast and --budget interop, easier budget goals

[simonmichael]

IceTec described a problem combining --forecast and bal --budget.

Here's a repro:

; budget goal rules

~ monthly  expenses budget
    (expenses)                                   200

; forecast txn rules

~ monthly  some expense
    assets
    expenses                                     100

--forecast uses all periodic rules in the period, including ones intended for setting budget goals:

$ hledger -f k.j --forecast reg expenses
2026-03-04 expenses budget       (expenses)                      200           200
2026-03-04 some expense          expenses                        100           300
2026-04-04 expenses budget       (expenses)                      200           500¯
2026-04-04 some expense          expenses                        100           600
2026-05-04 expenses budget       (expenses)                      200           800
2026-05-04 some expense          expenses                        100           900
2026-06-04 expenses budget       (expenses)                      200          1100
2026-06-04 some expense          expenses                        100          1200
2026-07-04 expenses budget       (expenses)                      200          1400
2026-07-04 some expense          expenses                        100          1500
2026-08-04 expenses budget       (expenses)                      200          1700
2026-08-04 some expense          expenses                        100          1800

I can exclude those here with not:desc:budget:

$ hledger -f k.j --forecast reg expenses not:desc:budget
2026-03-04 some expense          expenses                        100           100
2026-04-04 some expense          expenses                        100           200
2026-05-04 some expense          expenses                        100           300
2026-06-04 some expense          expenses                        100           400
2026-07-04 some expense          expenses                        100           500
2026-08-04 some expense          expenses                        100           600

but then they're excluded from bal --budget too, and no budget goals are shown.

$ hledger -f k.j --forecast bal -MN expenses not:desc:budget
Balance changes in 2026-03-01..2026-08-31:

          || Mar  Apr  May  Jun  Jul  Aug 
==========++==============================
 expenses || 100  100  100  100  100  100 

To work around, you have to (eg) move the budget rules into a separate file, then generate the forecast and do budget reporting in separate steps:

$ hledger -f k.j print --forecast | hledger -I -f- -f budget.j bal -MN expenses --budget
Budget performance in 2026-03-01..2026-08-31:

          ||              Mar               Apr               May               Jun               Jul               Aug 
==========++============================================================================================================
 expenses || 100 [50% of 200]  100 [50% of 200]  100 [50% of 200]  100 [50% of 200]  100 [50% of 200]  100 [50% of 200] 

How could we more precisely and intuitively exclude bal --budget's periodic rules from --forecast, or exclude bal --budget's generated goal transactions from reported amounts ?

[simonmichael]

• Use a different syntax for budget goal rules, separating these two features ?

• Manually add a budget: tag to budget goal rules, and make --forecast always ignore those ?

[simonmichael]

Making the features orthogonal would be the ideal, I think, if not too disruptive. It would be easier to understand and to use.

If budget goals got their own syntax, what would it be ? Eg:

budget monthly   
  (expenses)    200

But if we have a special syntax for budget goals, we could simplify it further: don't expect it to parse like a balanced transaction (requiring you to either add parentheses as above, or add a balancing posting which generates useless additional budget goals in the report).

budget PERIODEXPR  ACCT  AMT  [COMMENT]
B      PERIODEXPR  ACCT  AMT  [COMMENT]

B every 2 months   revenues  -500
B monthly         expenses:food  200    ; travel:

For selecting budget goals, --budget could take a query:

$ hledger bal --budget[=QUERY]
$ hledger bal --budget=food
$ hledger bal --budget=tag:travel

A multi-line syntax could be more convenient:

B PERIODEXPR  BUDGETNAME  [COMMENT]
  ACCT  AMT
  ...

B monthly  travel budget
  expenses:food      200
  expenses:lodging   400
  expenses:flights   500

--budget could match just the budget name (simpler):

$ hledger bal --budget[=NAMEPAT]
$ hledger bal --budget=travel

For compatibility, --budget could use only the new rules if any are found; otherwise use periodic transaction rules as before.

[wldcld]

You have already put some thoughts into it. I like your ideas regarding filterung on different budget names. I am not a seasoned hledger user nor a programmer. So please don't put too much weight on my thoughts. :) But, since I raised the question on reddit, I would like to share my humble opinion:

Biggest priority should be that this is a non breaking change.
The initial problem was the forecast creating virtual transactions from the recurring transaction that was only created for budgeting purposes. If we have an option to exclude certain recurring transactions from beeing interpreted by the --forecast switch, this would be sufficient to address the request. In the simplest form. So maybe a special tag placed at the recurring budget transaction to exclude it from the --forecast switch could be enough. Since the tag affects the behaviour of --forecast, it might be good to name it in context of the forecast switch. So maybe something like "no-forecast".
From a user perspective it could make sense to place it in the budget context. Like "budget-only".

Cheers