A foreign-currency party ledger makes the on-account residual invent money

[lamemustafa]

Summary

On a party ledger denominated in a foreign currency, CLOSINGBALANCE reads 0.00 while that party's
bill reports the full base-currency amount. Bridge computes the on-account residual as
CLOSINGBALANCE - sum(BILLCL), so it emits a residual equal to the entire outstanding with the
sign reversed — money that does not exist, on a document a CA sends to a client.

Measured 2026-08-23 on licensed TallyPrime Silver against a purpose-built book.

Reproduction

BRIDGE CORPUS FOREX, base currency INR. A $ currency master created over XML, then a party ledger
created with <CURRENCYNAME>$</CURRENCYNAME> — which Tally honours (readback shows currency='$'
where INR ledgers show 'I₹'). One Sales voucher for $1,000 at 83.50 = ₹83,500.

read	value
FX Sales CLOSINGBALANCE	115000.00 — includes the ₹83,500, so the voucher posted
Bills Receivable FXU-INV-001 BILLCL	-83500.00
FX USD Debtor 01 CLOSINGBALANCE	0.00

residual = CLOSINGBALANCE - sum(BILLCL) = 0.00 - (-83500.00) = +83500.00

Positive, where the real exposure is negative, and equal in magnitude to the whole receivable.

Why it is reachable

Bridge sends currency_assertion: "INR" on outstandings requests, and nothing has ever tested a
non-INR book against that path because no non-INR book existed. Bridge is read-only, so the
import-side behaviour below is not reachable in production — but this one is. It needs only a
customer with a single foreign-currency debtor.

The residual is not a corner case either. On the one real book measured, ~98.4% of the party balance
sat as unnamed On Account residual; it is the dominant number in an outstandings report.

Root cause, and one honest uncertainty

The leading explanation is that CLOSINGBALANCE on a foreign-currency ledger is expressed in the
ledger's own currency, while BILLCL is in base currency — so the subtraction crosses currencies.

That is not proven, because it was not possible to post a genuine forex amount to test it:
Tally silently discards FOREIGNAMOUNT and RATEOFEXCHANGE on import (CREATED=1 ERRORS=0 EXCEPTIONS=0, both fields absent on readback), so the voucher posts as a plain base-currency entry
against a foreign-denominated ledger.

What is certain is the observable disagreement between the two reads for the same party.

Suggested direction

The first requirement is to refuse rather than misreport, not to support multi-currency:

• detect a party ledger whose CURRENCYNAME differs from the company base currency
• withhold the report, or mark it partial with a specific reason, rather than emitting a residual
  computed across mismatched currencies
• CURRENCYNAME is fetchable on the ordinary ledger collection, so detection is cheap and needs no
  new request shape

This is the same principle the crosscheck work on #168 settled on: absence of contradiction is not
evidence, and a number that cannot be shown correct should not be published as complete.

[lamemustafa]

Correction and a much sharper result — the forex XML contract was found

Further probing changes this materially. Part of my original analysis was based on a broken
import, and I want to correct it before anyone acts on it.

The forex import contract is a composite AMOUNT string

FOREIGNAMOUNT and RATEOFEXCHANGE are not the import contract — that is why they were silently
discarded. Tally takes the currency, amount and rate as one string in <AMOUNT>:

sent:    <AMOUNT>$ -2000.00 @ 84.00</AMOUNT>
stored:  -$ 2000.00 @ I₹ 84/$  = -I₹ 168000.00

CREATED=1 ERRORS=0 EXCEPTIONS=0, and readback confirms Tally expanded it into its canonical form.
So multi-currency vouchers can be imported; my first attempt simply used the wrong shape.

The important consequence: CLOSINGBALANCE is not a number on a forex ledger

With a genuine forex amount posted:

FX USD Debtor 02   CLOSINGBALANCE = '-$ 2000.00 @ I₹ 84/$  = -I₹ 168000.00'
FXU-INV-002        BILLCL         = '-168000.00'

BILLCL stays a plain base-currency decimal. CLOSINGBALANCE becomes a composite display string.

What Bridge actually does with it — verified, not assumed

I ran the real parser against that exact string:

OK   "-168000.00"                                    -> ExactDecimal("-168000.00")
OK   "0.00"                                          -> ExactDecimal("0.00")
ERR  "-$ 2000.00 @ I₹ 84/$  = -I₹ 168000.00"         -> invalid_exact_decimal

parse_ledger_amount maps that to NativeOutstandingsError::InvalidAmount. Bridge fails closed.

That is the correct money behaviour and I should say so plainly: there is no silent
mis-computation in this path. My original framing — "invents money" — does not hold for a
correctly-posted forex book.

So the real defect is availability and diagnostics, not correctness

On any book containing a foreign-currency ledger, the whole outstandings read dies with a generic
InvalidAmount that blames the data. The operator is told nothing useful. A CA firm with one export
client gets a broken report and no explanation.

The zero case, stated honestly

The other ledger (FX USD Debtor 01) still shows CLOSINGBALANCE = 0.00 against a
BILLCL = -83500.00, which parses fine and does yield a phantom residual of +83500.00.

But I now believe that state is an artefact of my own broken import — a forex-denominated ledger
carrying a base-currency-only posting, because the discarded FOREIGNAMOUNT left the forex balance
at zero. Whether Tally's own UI permits a real book to reach that state is untested. Do not treat
it as a confirmed production defect on my say-so.

Revised suggestion

Unchanged in direction, clearer in reason: detect and report, rather than fail generically.

• CURRENCYNAME is fetchable on the ordinary ledger collection and identifies these ledgers before
  any amount is parsed
• emit a specific reason — "this book has a foreign-currency ledger, which Bridge cannot value" —
  instead of InvalidAmount
• decide deliberately whether to withhold the whole report or exclude those parties and mark partial

Priority is lower than the original report implied: fail-closed already protects the money. What is
missing is the operator being told why.

Corpus: BRIDGE CORPUS FOREX, synthetic. Measured on licensed TallyPrime Silver, 2026-08-23.

[lamemustafa]

Correction — the detection machinery already exists; one path does not use it

My earlier suggestion ("detect a party ledger whose CURRENCYNAME differs from base, withhold or
mark partial") implied building something new. That was wrong, and the real defect is smaller and
more specific.

What already exists and is correct

CompanyCurrency { symbol, mailing_name, currency_count, is_inr }
(native_outstandings/model.rs:133), with a deliberately conservative rule at wire.rs:1000:

is_inr = currency_count == 1 && mailing_name.eq_ignore_ascii_case("Indian Rupees")

INR is inferred only when the company defines exactly one currency master. The existing comment
gives the reason: with several defined, which one is BASE is not determinable from that read, and
guessing "would put a wrong currency symbol in front of a real balance." That reasoning is right and
should be kept as-is.

The all-companies sweep already enforces it (commands.rs:2253):

Ok(currency) if !currency.is_inr => Err("company_base_currency_not_inr")

The actual defect

The single-company command never calls it. fetch_tally_outstandings (commands.rs ~2100–2122)
validates the company name, resolves the as-of date, and goes straight to fetch_outstandings.
detect_base_currency appears at only two call sites in commands.rs — 2245 and 3350 — and neither
is this one.

So the same company is refused by one path and rendered in rupees by the other.
OutstandingsScreen then prints ₹ through currencySymbol(currencyAssertion: "INR") (line 1013),
whose never guard makes it type-safe while proving nothing about the book.

Measured: BRIDGE CORPUS FOREX defines two currency masters — I₹ (mailing name INR) and $ — so
is_inr is false for it. The sweep would refuse that book; a single-company read would not.

Revised scope

1. Apply the existing gate on the single-company path, with the same reason code. Preferably by
   lifting the check somewhere a third caller cannot omit it — the same shape as Redacted proof export rejects every warning code Bridge produces (adaptive_window_split breaks export and drill-down) #162, N13 — render party statements despite unrepresentable names, and show the ageing subtotals #163 and Bill direction is a stringly-typed value with a silent receivable fallback #164.
2. AllClientsScreen.tsx hardcodes ₹ at lines 60, 71, 72, 73 with no assertion at all, unlike
   OutstandingsScreen. Latent today because those rows are gated upstream, but the two screens
   should not sit on different footings unsaid. This overlaps docs(tally): Unit A review follow-ups — empty-partition corroboration, breaker feed, telemetry, currency #107 item 4.

The per-ledger case stays out of scope

The forex-denominated ledger described above returns
CLOSINGBALANCE = '-$ 2000.00 @ I₹ 84/$ = -I₹ 168000.00', which parse_ledger_amount correctly
rejects as invalid_exact_decimal. Bridge fails closed; there is no wrong money. Improving that
diagnostic needs CURRENCYNAME added to a ledger fetch and a template repin — a different cost
class, and worth a separate issue rather than widening this one.

Corrected after reading the call sites rather than the issue text. The detection was there; the
omission was a missing call.

[lamemustafa]

Closing. The actionable work is done; the title was wrong and the residual is a capability gap rather than a defect.

The original claim was wrong, and I corrected it above

This issue was filed saying a foreign-currency ledger makes Bridge "invent money" — a residual equal to the whole receivable with the sign reversed. Bridge never emits that number. On a forex ledger CLOSINGBALANCE arrives as a composite display string (-$ 2000.00 @ I₹ 84/$ = -I₹ 168000.00) rather than a decimal, so parse_ledger_amount fails and the read aborts. It fails closed. That correction is in the comment above and stands.

What was actually wrong, and is now fixed

The diagnostic. The failure surfaced as InvalidAmount — "Tally returned an invalid native amount" — which reads as though Tally sent garbage rather than as "this company is foreign-currency". On the measured book ~98.4% of the party balance sat in the unnamed residual, so an operator had nothing to act on.

Fixed in the N17 work on #177: a typed error that recognises the composite shape structurally rather than by symbol, names the offending ledger, and reaches the sweep as well as the single-company screen. Bridge still fails closed and that is deliberate — no attempt is made to parse the composite string or fall back to its base-currency tail.

Note this closes on the strength of #177, which is green and pending merge at the time of writing. If that PR is abandoned rather than merged, reopen this.

What remains, and why it is not this issue

Bridge cannot produce an outstandings report for a foreign-currency book at all. That is a capability gap, not a defect: the residual arithmetic CLOSINGBALANCE - sum(BILLCL) needs a base-currency decimal, and Tally does not supply one for such a ledger through this collection. Supporting those books needs a different read, not a fix to this one.

Worth recording for whoever picks that up: any company holding a foreign-currency ledger necessarily defines a second currency master, so parse_company_currency returns is_inr = false and the bulk sweep refuses it at the currency preflight before the read is even attempted. Multi-currency support therefore starts at that gate, not at the parser.

Also settled along the way (measured 2026-08-23, licensed Silver 7.1): the forex import contract is a composite AMOUNT string, FOREIGNAMOUNT/RATEOFEXCHANGE are silently discarded, and a party ledger honours <CURRENCYNAME>. Detail is in the private brain repo.