Measure whether a same-REMOTEID import with changed content replaces a voucher or merges into it

[lamemustafa]

Blocks any idempotent correction path for the writer, and is cheap to answer.

What is established

TALLY_PROTOCOL_REFERENCE.md §3.3a:

import #1  REMOTEID="…-001"  ->  CREATED=1  ALTERED=0
import #2  byte-identical    ->  CREATED=0  ALTERED=1
vouchers in Tally afterwards ->  1

So a client-supplied REMOTEID makes a repeat upsert rather than duplicate.

What is not

The measured repeat was byte-identical. That establishes idempotency on retry. It says nothing about amendment, which is the case any correction path actually needs:

1. Does a same-REMOTEID import carrying different content replace the voucher's entry set, or merge into it? If a corrected voucher has fewer legs than the original, do the removed legs survive? A merge would leave an unbalanced voucher, and a correction path built on it would be worse than duplicating.
2. §9.8's scope limit applies: upsert-on-repeat is verified on the licensed Journal path and UNVERIFIED for every other voucher type — including the Payment, Receipt and Contra that a bank statement is made of.

Why it matters now

Bridge derives REMOTEID = SHA256("bridge.mcp.import.v1", batch_id, txn_id) with a random per-build batch_id, deliberately, so that a caller's reused transaction label cannot become a silent upsert key. The consequence is that rebuilding a corrected business event duplicates it. The operator-side scripts/bank_statement_import.py takes the opposite approach — a stable content-addressed REMOTEID — and uses re-import as its correction path.

A design that reconciles the two is written up in the knowledge base as idempotent-correction-needs-a-compare-and-swap-not-a-stable-key: amend a Bridge-owned batch, under a read-back compare-and-swap so the upsert is never blind. That design survives reasoning and still dies if Tally merges rather than replaces, which is why this measurement should come before anything is built.

Proposed measurement

On a synthetic company, not a client book:

1. Post a two-leg Journal with a client REMOTEID. Read back.
2. Re-post the same REMOTEID with one amount changed. Read back — replaced or merged?
3. Re-post the same REMOTEID with one leg removed. Read back — does the removed leg survive?
4. Repeat 1–3 for Payment, to test §9.8's scope limit directly.

Record the captured responses, not counts: a repeat that was rejected, or whose transport failed before Tally processed it, also leaves the voucher count unchanged.

Note on the environment

As of this morning the lab gateway answers HTTP 200 but no company is loaded — List of Companies returns STATUS=0, LINEERROR: Could not find Report and the Company collection returns STATUS=1 with zero <NAME> elements. Someone has to load a company at the machine before this can be run.

[lamemustafa]

Measured. A same-REMOTEID import with changed content replaces the voucher's entry set. It does not merge, and it does not duplicate. Holds for Journal and for Payment, closing the half of §9.8's scope limit a bank statement depends on.

Environment

Licensed TallyPrime 7.1 Silver, port 9001. Writes into BRIDGE SHAPE LAB only (guid 3a6bd6e1-…, company no. 100021), date 20250415. Envelope and voucher shape copied byte-for-byte from Bridge's render_import_envelope / render_import_xml, so this measures the shape Bridge produces rather than a hand-written one.

Result

step	sent	import	voucher afterwards
j1	Journal, 3 legs, new REMOTEID	CREATED=1	3 legs: −100 / 60 / 40
j2	same REMOTEID, amounts changed	CREATED=0 ALTERED=1	same GUID, −150 / 90 / 60
j3	same REMOTEID, one leg removed	CREATED=0 ALTERED=1	2 legs, −100 / 100 — removed leg gone
p1	Payment, 3 legs, new REMOTEID	CREATED=1	3 legs: −300 / −200 / 500
p2	same REMOTEID, amounts changed	CREATED=0 ALTERED=1	−450 / −250 / 700
p3	same REMOTEID, one leg removed	CREATED=0 ALTERED=1	2 legs, −500 / 500 — removed leg gone

Voucher count stayed at exactly 1 per REMOTEID throughout, and ALTERID advanced 62→63→64 and 65→66→67. Read back after every step by narration marker rather than REMOTEID, since the attribute does not echo the client key.

What this settles

The design in idempotent-correction-needs-a-compare-and-swap-not-a-stable-key rested on exactly this premise, and it would have died on a merge. It holds: amending a Bridge-owned batch under a read-back compare-and-swap is an available correction path, because re-sending a corrected voucher under its original REMOTEID really does converge to the corrected voucher.

Limits — not measured

• Receipt and Contra. Receipt mirrors Payment structurally, so replacement is likely; Contra is not established.
• Adding a leg. Only change and removal were tested.
• Changing the voucher type, date or party under the same REMOTEID.
• One licensed instance, one release.

How misrouting into a client book was prevented, not just detected

All 22 companies were loaded, including a real client book. A read-back only detects a misroute after a voucher is already in that book. So:

1. Proved unknown ledgers fail closed with a canary naming ledgers that exist nowhere: CREATED=0, LINEERROR: Ledger '…' does not exist!, nothing created in either company.
2. Every write used only ledgers that exist in Shape Lab and not in the client book — 38 such ledgers out of 43. A misrouted import therefore fails on an unknown ledger instead of landing.
3. Re-verified Shape Lab's GUID and company number immediately before every write, and read a count only from the client book after every write. It stayed 0.

One trap from the canary worth recording: it came back ERRORS=0 with EXCEPTIONS=1. A check that treats ERRORS == 0 as success reads that failed import as a success.

Two PROBE429: vouchers remain in Shape Lab, both carrying REMOTEIDs and so removable over XML. Left in place as inert markers.

[lamemustafa]

Closing. The limits listed in the measurement above are now measured, apart from the last one (one licensed instance, one release). The correction path this issue gated shipped in #439.

Same environment and guards as before: licensed TallyPrime 7.1 Silver, writes into BRIDGE SHAPE LAB only, envelope copied from Bridge's renderer, only ledgers that exist in Shape Lab and not in the loaded client book, Shape Lab identity re-read before every write, and a count-only read of the client book after every write (0 every time). The unknown-ledger canary was re-run first today and still fails closed (CREATED=0, EXCEPTIONS=1, LINEERROR).

Measured while building #439

step	sent under the same REMOTEID	import	voucher afterwards
r1→r2	Receipt, amounts changed	CREATED=0 ALTERED=1	875 / 875, same voucher
r3	Receipt, party changed	CREATED=0 ALTERED=1	party leg now Shape Buyer 2
c1→c2	Contra, amounts changed	CREATED=0 ALTERED=1	1250 / 1250, same voucher
j4	Journal, leg added (2→3)	CREATED=0 ALTERED=1	3 legs: −120 / 70 / 50
p4	Payment, date changed	CREATED=0 ALTERED=1	dated 20250416, one voucher
t1→t2	Payment re-sent as Receipt	CREATED=0 ALTERED=1	now a Receipt, one voucher

Measured today: adding and removing a leg

step	sent under the same REMOTEID	import	voucher afterwards
r4	Receipt, leg added (2→3)	CREATED=0 ALTERED=1	−875 / 500 / 375, same GUID
r5	Receipt, leg removed (3→2)	CREATED=0 ALTERED=1	−875 / 875, removed leg gone
c3	Contra, leg added (2→3)	CREATED=0 ALTERED=1	−1250 / 1000 / 250, same GUID
c4	Contra, leg removed (3→2)	CREATED=0 ALTERED=1	−1100 / 1100, removed leg gone
p5	Payment, leg added (2→3)	CREATED=0 ALTERED=1	−500 / −125 / 625, date kept

Exactly one voucher per REMOTEID after every step. ALTERID advanced 80→84 across today's steps.

Result: for Journal, Payment, Receipt and Contra, a same-REMOTEID import replaces the whole voucher in place: entries, party, date and even voucher type. It never merges and never duplicates.

Still not measured

• Contra's added leg was a second entry on a ledger already in the voucher. Shape Lab has only two bank ledgers that aren't also in the client book, and creating a third would itself be a write that could be misrouted. Adding a leg on a different ledger is measured for Receipt, Payment and Journal only.
• One licensed instance (7.1 Silver), one release. Another client book on 7.1 Gold imported cleanly through Bridge-built files, but no amendment has been run there.

The probe vouchers (PROBE429:*, PROBEAMEND:*) remain in Shape Lab. All carry REMOTEIDs, so they can be removed over XML.