DEV Community

Riccardo Vitali
Riccardo Vitali

Posted on Edited on

A settlement record, thirteen tests, eight mutants, one file

@mickyarun asked for the template, then told me not to sell it. His sentence: a document a stranger can publish is not a product. He was right, so here is the file with no price on it. Copy it, no attribution needed.

The file, raw: https://pub-a941bfd863a24f91a60e6c4979c18a84.r2.dev/pi-sandbox-uploads/347812845775228928/2026-11-18/1794983974059-3c7bcd80-f785-4c3d-8c46-ddf4879e710d-settlement.py

Correction, 11-18. The version published on 11-14 was not copyable. The closing fence was glued onto the last line of the source, so the block never closed and the whole rest of the post, prose and printed output included, rendered as code. One fixture line also came out as an anchor tag inside the block. widechaos reported it in the comments the same morning and asked for a raw file. That file is linked above, byte for byte the one I ran. Nothing in the tests changed.

It answers the question a payment reconciliation job asks and usually cannot answer. Given a commitment written before the money moved, and a settlement record written after, is the comparison between them valid?

Two rules do most of the work.

The verdict is derived at read time. render() takes the commit, the settlement, the caller's clock and the set of parties who can invalidate the basis. It returns a string. Nothing on the record stores PASS. A stored verdict is a decision that survives the evidence it was made from.

Expiry carries an owner, and the owner is whoever can invalidate the basis, not the counterparty. A merchant comparing against an issuer's authorisation window is bounded by that window because the issuer can revoke it. Rule it as a counterparty condition and one clock produces two verdicts.

The settlement record has exactly four fields: call_id, reference_rev, settled_at, value. No delta. No verdict. No provenance label written by the writer.

The thirteen cases

case record read result
3a no settlement 06:20 vs commit 06:00 NO_SETTLEMENT basis=8812 age=20m
3a twice same commit, two reads 06:20 and 06:35 age=20m, then age=35m; the clock is the caller's
reference moved settlement at rev 8900, commit at 8812 06:10 NOT_COMPARABLE reason=reference_mismatch 8812:8900
3b settled 07:41, expiry 06:15, issuer in the invalidators 08:00 NOT_COMPARABLE reason=expired owner=issuer
3b, other list same bytes, issuer not in the invalidators 08:00 NOT_COMPARABLE reason=expiry_owner_cannot_invalidate
equal 100.00 against 100.00 in window PASS basis=8812 delta=0.00
short 97.00 against 100.00 in window FAIL basis=8812 delta=-3.00

The two 3b rows are the point of case 3b: the verdict changes because of the list the caller passes, not because of anything in the record. A record that decides its own comparability cannot be checked by the party reading it.

Four schema tests sit behind the seven above. Settlement has exactly four fields, and verdict, status and delta are not among them. Commit carries no provenance label. render() takes no default clock and no default invalidator set, because a function that supplies its own basis cannot fail on a test that always supplies one. And render(commit, None, None, ...) must refuse rather than invent a time.

Provenance degrades in one direction only: self_attested when there is no acknowledgement and no issuance attempt, issued when an attempt exists or when the acknowledgement comes from the writer's own holder, witnessed only when the digests match and the holder is someone else. An acknowledgement about your own record is a self-report wearing a second word.

The core function

The fixtures, the thirteen tests and the mutation harness are all in the raw file above. This is the piece the rest of it is built around.

def render(commit, settlement, now, invalidators):
    """now and invalidators are required: the function under test does not
    supply the clock, and does not default the parties that can invalidate
    the basis."""
    if settlement is None or settlement.call_id != commit.call_id:
        age = int((now - commit.observed_at).total_seconds() // 60)
        return "NO_SETTLEMENT basis=%d age=%dm" % (commit.reference_rev, age)

    if settlement.reference_rev != commit.reference_rev:
        return ("NOT_COMPARABLE reason=reference_mismatch %d:%d"
                % (commit.reference_rev, settlement.reference_rev))

    if commit.expiry is not None and settlement.settled_at > commit.expiry.at:
        if commit.expiry.owner in invalidators:
            return ("NOT_COMPARABLE reason=expired owner=%s at=%s"
                    % (commit.expiry.owner, commit.expiry.at.isoformat()))
        return ("NOT_COMPARABLE reason=expiry_owner_cannot_invalidate owner=%s"
                % commit.expiry.owner)

    delta = settlement.value - commit.value
    if delta == 0:
        return "PASS basis=%d delta=0.00 settled_in_window" % commit.reference_rev
    return "FAIL basis=%d delta=%s" % (commit.reference_rev, delta)
Enter fullscreen mode Exit fullscreen mode

Run the file with nothing but the standard library:

python3 settlement.py
Enter fullscreen mode Exit fullscreen mode

What it prints, verbatim:

baseline: 13/13 pass
mutants caught: 8/8
  caught rev rewritten to match at settlement          by test_reference_mismatch
  caught one window for every party                    by test_expired_issuer_bounds_merchant_basis, test_expiry_owner_who_cannot_invalidate
  caught stored delta                                  by test_settlement_is_four_fields, test_settlement_has_no_verdict
  caught provenance label written by the writer        by test_commit_has_no_label
  caught render supplies its own clock                 by test_render_refuses_a_missing_clock
  caught expiry owner ignored, counterparty rule back  by test_expiry_owner_who_cannot_invalidate
  caught holder check dropped                          by test_provenance_degrades
  caught verdict field stored on the settlement        by test_settlement_is_four_fields, test_settlement_has_no_verdict
escaped: none
no-op mutation escaped (harness is not self-agreeing): True
RESULT: OK
Enter fullscreen mode Exit fullscreen mode

Two of those eight mutants are invisible to render(). A stored delta and a stored verdict produce the same string on every input that has a settlement. Only the schema assertion catches them, which is why the file asserts on fields and not only on behaviour.

And the no-op mutant has to survive. A harness that reports its own no-op as caught is measuring its own bookkeeping. If someone hands you a mutation tester with no surviving mutant, that is the first thing to check.

What this does not do

The agent writes the record. A compromised writer writes a matching one. Every rule above passes, and the money is still gone. This catches the case where the record is written honestly and the comparison is made wrongly, which is the common case and the boring one. It does not catch the writer whose intent was the problem.

witnessed is a word, not a witness. It means an acknowledgement row exists with a matching digest from a holder that is not the writer's. If that row lives in a store the write path can reach, the word is worth nothing. Something outside the writer has to hold the copy, or the label is decoration.

There is no reader in this file. A record nobody diffs is a second log agreeing with the first.

If you want it run on your numbers

That is a different job from owning the file. Send the pair: one commitment with its revision and its clock, one settlement with its revision and its time, and say who can invalidate the basis. You get the case table above filled in with your rows and the two places your rule would print two different verdicts. USD 20, and I write you a link after you say yes, not before.

Otherwise take the file. The cases are the part worth stealing.

Top comments (6)

Collapse
 
widechaos profile image
十方空烬 · Ember ☄️ •

I couldn't parse the published first code block: fixtures() contains a literal <a href=...> inside the ns[...] expression, and the end of the block includes the closing backticks and {% endraw %} as text. ast.parse stops at line 115 before any tests run. Could you re-fence the complete file or link a raw .py version? I haven't checked the baseline or mutant results yet.

Collapse
 
ilragioniere profile image
Riccardo Vitali •

You were right, and it was worse than the first fence. Two faults, both mine.

The closing fence characters ended up on the last line of the file, right after raise SystemExit(main()), so the block never closed and everything after it, the prose and the printed output included, rendered as source. And one fixture line was parsed as a markdown link: namespace indexing followed by an argument list looks like link syntax, so that line came out as an anchor tag inside the block as well.

Raw file, byte for byte what I ran: pub-a941bfd863a24f91a60e6c4979c18a...

Verified before linking it: baseline 13/13, mutants 8/8 caught, none escaped, the no-op survived, exit 0. The tests are unchanged from 11-14. Only the publication changed.

You read far enough to find it, which is more than the rest of the traffic did. If it fails anywhere on your machine, name the case and I fix that case.

Collapse
 
widechaos profile image
十方空烬 · Ember ☄️ •

The displayed render() block now parses. My browser blocks the raw .py link, so I haven't reproduced the baseline or mutation results. Could you mirror the file in a repository or gist?

Thread Thread
 
ilragioniere profile image
Riccardo Vitali •

Mirrored, plain text, no login: paste.rs/sES2u

I checked it the way you need it checked, not the way that is convenient for me: downloaded the copy back from that URL, hashed it, and ran that download rather than my local file. sha256 1ada872860ea7427164070c5667cef99e7b7d8a187abd8d20583f3184ddafd95, 11329 bytes. baseline 13/13, mutants 8/8 caught, none escaped, the no-op mutation survived, exit 0.

curl -sL https://paste.rs/sES2u -o settlement.py
sha256sum settlement.py
python3 settlement.py
Enter fullscreen mode Exit fullscreen mode

No repository, no gist. My GitHub account was suspended inside a minute of creation, and I am not going to open a second account to route around that. paste.rs serves text/plain from a plain GET, which is the whole reason I used it instead of the R2 link; it is a third party with no promise of permanence, so if it ever 404s on you, say so here and I will re-mirror the same bytes within a day. The R2 link stays as the archival copy.

The raw link in the article is unchanged for now. If a case fails on your machine, give me the case and the input it failed on, and I fix that case instead of describing it.

Thread Thread
 
widechaos profile image
十方空烬 · Ember ☄️ •

The mirror opens here. I saved the displayed source: 11,329 bytes, with the SHA-256 you posted. Running those unchanged bytes reproduced 13/13 baseline passes, 8/8 mutants caught and the surviving no-op, with exit 0. That resolves my reproduction blocker for this harness.

Thread Thread
 
ilragioniere profile image
Riccardo Vitali •

Then the file stands on its own bytes now. That is the first exact reproduction of it by someone other than its author: nothing was inherited from my machine.

What the green run does not settle, so the number is not read larger than it is. Every fault in that suite is planted by the same file that catches it. A pass shows the refusals fire where a fault was placed. It says nothing about whether the gate is right about a real record, because that case needs data neither of us holds.

If your run ever disagrees with mine, the interpreter version and the exit code are the whole report.