budget.scrubSigns

Run GnuCash's natural-signs scrub: guess each budget's old sign convention and flip amounts to match.

Runs GnuCash's natural-signs scrub on a book whose budgets predate GnuCash 3.8, which stored amounts with the signs of the user's display preference. For each budget it guesses the old convention from the sums of its amounts and flips the amounts to natural signs, then sets the book feature Use natural signs in budget amounts. It rewrites amounts on a guess, so it is destructive: look at the budgets after, as GnuCash asks.

GnuCash runs this every time a file opens; red-ale does not, and until you run it every budget edit is refused with conflict (reason natural-signs). budget.list tells you when it is needed. With no budgets it only unsets a feature left over. Each result says which policy was guessed (incomeExpense, creditAccounts, none) and how many amounts were flipped.

Examples

Example: with a copy of the reports/budget example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"budget.setAmounts","params":{"budget":"f0000000000000000000000000000000","amounts":[{"account":"Root:Expenses","period":0,"amount":"1"}]}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": 2003,
    "message": "…",
    "data": {
      "reason": "natural-signs",
      "help": "error/conflict"
    }
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"budget.scrubSigns","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "featureSet": true,
    "featureUnset": false,
    "budgets": [
      {
        "budget": "f0000000000000000000000000000000",
        "policy": "none",
        "flipped": 0
      }
    ]
  }
}

Request:

{"jsonrpc":"2.0","id":3,"method":"budget.list","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "naturalSigns": true,
    "needsSignScrub": false,
    "…": "…"
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
budget.setAmounts {"budget":"f0000000000000000000000000000000","amounts":[{"account":"Root:Expenses","period":0,"amount":"1"}]}
budget.scrubSigns {}
budget.list {}
EOF

It fails with exit status 2, printing on standard error:

{
  "error": {
    "code": 2003,
    "message": "…",
    "data": {
      "reason": "natural-signs",
      "help": "error/conflict"
    }
  }
}

MCP tool call

Tool call:

{"name":"budget.setAmounts","arguments":{"budget":"f0000000000000000000000000000000","amounts":[{"account":"Root:Expenses","period":0,"amount":"1"}]}}

Result:

{
  "isError": true,
  "structuredContent": {
    "error": {
      "code": 2003,
      "name": "conflict",
      "message": "…",
      "data": {
        "reason": "natural-signs",
        "help": "error/conflict"
      }
    }
  }
}

Tool call:

{"name":"budget.scrubSigns","arguments":{}}

Result:

{
  "structuredContent": {
    "featureSet": true,
    "featureUnset": false,
    "budgets": [
      {
        "budget": "f0000000000000000000000000000000",
        "policy": "none",
        "flipped": 0
      }
    ]
  }
}

Tool call:

{"name":"budget.list","arguments":{}}

Result:

{
  "structuredContent": {
    "naturalSigns": true,
    "needsSignScrub": false,
    "…": "…"
  }
}

Effect: destructive, on the Book.

Params

Params for methods that take none.

Type: NoParams.

Result

The result of budget.scrubSigns.

featureSet (boolean, required): The feature was set.
featureUnset (boolean, required): The feature was unset, as the book has no budgets.
budgets (array of BudgetScrubInfo, required): Each budget scrubbed, in book order.