September 2026

Golden tests for laytime: why the expected value is never updated

A laytime calculation is a claim for money. Here is how we made ours reproducible, disputable and boring, and why the engine is now open source.

Every voyage charter ends with a small argument about time. The charterer had a number of days to load and discharge the cargo; if they used more, they owe demurrage; if less, the owner owes despatch. On a 10,000 DWT coaster in the Black Sea, a day of demurrage is a few thousand dollars, which is a large share of the voyage result. The calculation is done from a Statement of Facts, a timeline of what happened in port, against the counting rules of the charter party.

In most small owners' offices this is a spreadsheet, rebuilt by hand for each voyage, argued over by email. When we wrote the laytime module for MarOps, a back-office application for exactly those offices, we had three requirements that a spreadsheet cannot meet:

The same input must give the same answer six months later, when the claim is disputed.
Every deduction must be a record with a start and an end, never "minus eight hours".
A change to the code must not be able to quietly change a number that has already been sent to a counterparty.

This post is about the third one, but the first two shape it.

The basis is the evidence

The engine is a single pure function:

result = compute_laytime(basis)

basis is one JSON document holding everything the calculation needs: the charter-party counting rules, the demurrage rate, and one entry per port with NOR, completion time, the allowance and the list of interruptions. It contains no references to anything else, no database ids, no clock reads. result is a JSON document with the used days, demurrage and despatch, in Decimal strings.

MarOps stores the basis in a JSONB column next to the result. When a counterparty disputes a statement, the office does not reconstruct anything; it replays the stored basis and gets the stored result. If the counterparty argues that a Sunday should not have counted, the office changes one flag in a copy of the basis, replays it, and both sides see exactly what that argument is worth. The argument becomes a diff between two JSON documents.

That only works if the function really is pure, and if its behaviour does not drift. Which brings us to the tests.

What a golden test is here

The test file opens with this:

Every expected value was verified by hand against the charter-party rule it exercises. If the engine changes and one of these fails, the engine is wrong; these tests are never "fixed" by updating the expected value.

Each test is one rule, one small statement of facts, and the number a person worked out on paper before the code existed. For example, once on demurrage, always on demurrage:

def test_golden_once_on_demurrage():
    """After demurrage starts neither rain nor Sunday is deducted."""
    rain_after = {"from": "2026-03-04T10:00", "to": "2026-03-04T16:00", "reason": "rain"}
    result = compute_laytime(
        basis(
            {"laytime_basis": "SHEX"},
            [port(completed="2026-03-09T08:00",
                  allowed={"kind": "fixed_days", "days": "1"},
                  interruptions=[rain_after])],
        )
    )
    assert result["ports"][0]["demurrage_start"] == "2026-03-03T08:00"
    assert result["demurrage_days"] == "6.00000"
    assert result["demurrage_amount"] == "48000.00"

Laytime starts Monday 2 March at 08:00, one day is allowed, so demurrage starts Tuesday 3 March at 08:00. Cargo completes the following Monday. Between those two moments there is a six-hour rain stoppage and a full Sunday. Under SHEX both would be deducted before demurrage; after it, neither is. Six full days at 8,000 a day: 48,000. A person can check every line of that with a calendar and a pencil.

The companion test moves the same rain stoppage to before demurrage starts and asserts that it now shifts the demurrage start by six hours and reduces the bill to 46,000. A third test flips the charter-party exception flag and shows the rain being deducted after demurrage. Three tests, one rule and its two edges.

Why "never update the expected value" is the whole point

The usual life of a test suite: a refactor changes an output, the test fails, the developer looks at the new output, decides it looks fine, and updates the assertion. For most code that is reasonable. For this code it is the exact failure we are trying to prevent.

If an engine change turns 48,000 into 46,000 and someone updates the test, then every statement already sent out with 48,000 on it is now contradicted by the office's own software. The counterparty's lawyer will find that.

So the policy is asymmetric. A golden test failing means one of two things:

the engine is wrong, and the code is fixed until the test passes, or
the rule itself has changed, in which case the old test keeps its number under the old rule (which becomes a flag in the basis), and a new test is added with a new hand-verified number under the new rule.

Either way, an existing basis replays to its existing result. Old statements stay true. The basis carries the rule, so old and new can coexist.

What the rules had to be

Getting to hand-verifiable examples forced us to make each rule explicit as a field in the basis rather than an assumption in the code. The set that survived:

SHINC counts everything; SHEX and WWD skip Sundays and a list of holidays. Weather is not inferred; a weather stoppage is an interruption record. So WWD and SHEX are the same to the engine, and the difference is in what the office records.
unless_used: excepted days count anyway, and idle time on them is deducted through interruption records like any other.
nor_to_start_hours: the gap between NOR acceptance and the start of counting.
Allowance as fixed days or as cargo quantity divided by a daily rate.
Half or full despatch, on working time saved or all time saved. The second is the subtle one under SHEX: the unused allowance has to be projected across the calendar, Sundays included, to find when it would have run out. There is a golden test where the same two days early are worth four days on working time and five on all time.
Reversible laytime: one pooled ledger across ports, so time saved at loading carries to discharge. The test shows the same two port calls giving half a day of demurrage pooled and one and a half days plus a day of despatch when settled separately. Same facts, two numbers, both correct under their own clause.
Once on demurrage, always on demurrage, with an explicit opt-out flag for charter parties that say otherwise.

Everything else, notably charter-party text interpretation and the parsing of the Statement of Facts, is deliberately outside the function. The engine takes facts and rules; deciding what the facts are is a human's job.

Two implementation choices that made the tests possible

Whole seconds and Decimal. Time is counted in integer seconds and converted to days only for output, as a five-decimal string rounded half-up. Money is Decimal at two places, from a per-day rate pro rata by seconds. Nothing is a float, so 0.1 plus 0.2 never appears, and a result can be compared with == against a string a person wrote down.

Intervals are merged before counting. Interruptions and excepted days are both intervals on the port-local timeline. They are clipped to the laytime window, merged, and the countable time is what is left. A rain stoppage that overlaps a Sunday is therefore not deducted twice, and overlapping interruption records from a messy SOF do not inflate the deduction. The merge is a few lines and it is where most hand-calculation errors in spreadsheets come from.

Open-sourcing the engine

The engine has no dependencies and reads no state, so we extracted it into a standalone package, laytime, under the MIT licence. The golden tests went with it unchanged.

The reasoning is the same as for the stored basis. A laytime statement is a claim against someone else. If that someone can install the package, feed it the basis printed on the statement, and get the same number, the statement is stronger, not weaker. There is nothing proprietary in how Sundays are skipped; the value of the product is in capturing the facts quickly and keeping them.

pip install laytime
laytime basis.json

What we would tell a small office

Keep the basis. Whatever tool you use, the input that produced a statement should be stored, unmodified, beside the statement. If you can replay it, you can defend it. If your tool cannot show you the exact input it used, it is not a calculator, it is an opinion.

The engine: github.com/oktaybobus/laytime. MarOps case study: zdeck.tech/case-study-marops.html.

Eylül 2026

Laytime için altın testler: beklenen değer neden hiç güncellenmez

Bir laytime hesabı bir para talebidir. Bizimkini nasıl yeniden üretilebilir, tartışılabilir ve sıkıcı hale getirdiğimizi ve motorun neden artık açık kaynak olduğunu anlatıyoruz.

Her sefer çarteri, zaman üzerine küçük bir tartışmayla biter. Çarterer'ın yükü yüklemek ve tahliye etmek için belirli sayıda günü vardı; daha fazlasını kullandıysa demuraj borçludur, daha azını kullandıysa armatör dispeç borçludur. Karadeniz'de 10.000 DWT'lik bir koster için bir günlük demuraj birkaç bin dolardır; bu da sefer sonucunun büyük bir payıdır. Hesap, limanda ne olduğunun zaman çizelgesi olan Statement of Facts üzerinden, çarter partinin sayım kurallarına göre yapılır.

Çoğu küçük armatör ofisinde bu bir elektronik tablodur; her sefer için elle yeniden kurulur, e-postayla tartışılır. Tam da bu ofisler için bir arka ofis uygulaması olan MarOps'un laytime modülünü yazarken, bir tablonun karşılayamayacağı üç gereksinimimiz vardı:

Aynı girdi altı ay sonra, talep itiraz gördüğünde aynı cevabı vermeli.
Her kesinti başlangıcı ve bitişi olan bir kayıt olmalı; asla "eksi sekiz saat" olmamalı.
Koddaki bir değişiklik, bir karşı tarafa çoktan gönderilmiş bir sayıyı sessizce değiştirememeli.

Bu yazı üçüncüsü hakkında, ama ilk ikisi onu şekillendiriyor.

Dayanak kanıtın kendisidir

Motor tek bir saf fonksiyondur:

result = compute_laytime(basis)

basis, hesabın ihtiyaç duyduğu her şeyi tutan tek bir JSON belgesidir: çarter partinin sayım kuralları, demuraj oranı ve her liman için NOR, tamamlanma zamanı, izin verilen süre ve kesinti listesiyle birer giriş. Başka hiçbir şeye referans içermez; veritabanı id'si yok, saat okuması yok. result ise kullanılan günleri, demuraj ve dispeci Decimal dizeleri olarak taşıyan bir JSON belgesidir.

MarOps dayanağı sonucun yanındaki bir JSONB sütununda saklar. Bir karşı taraf bir statement'a itiraz ettiğinde ofis hiçbir şeyi yeniden kurmaz; saklanan dayanağı yeniden oynatır ve saklanan sonucu alır. Karşı taraf bir pazarın sayılmaması gerektiğini savunursa ofis dayanağın bir kopyasında tek bir bayrağı değiştirir, yeniden oynatır ve iki taraf da o iddianın tam olarak ne ettiğini görür. Tartışma, iki JSON belgesi arasındaki bir diff'e dönüşür.

Bu ancak fonksiyon gerçekten safsa ve davranışı kaymıyorsa işe yarar. Bu da bizi testlere getiriyor.

Burada altın test ne demek

Test dosyası şöyle açılır:

Her beklenen değer, sınadığı çarter parti kuralına karşı elle doğrulanmıştır. Motor değişir ve bunlardan biri başarısız olursa yanlış olan motordur; bu testler beklenen değer güncellenerek asla "düzeltilmez".

Her test tek bir kural, küçük bir statement of facts ve kod var olmadan önce bir insanın kâğıt üzerinde hesapladığı sayıdır. Örneğin demuraja bir kez girildi mi hep demurajda:

def test_golden_once_on_demurrage():
    """After demurrage starts neither rain nor Sunday is deducted."""
    rain_after = {"from": "2026-03-04T10:00", "to": "2026-03-04T16:00", "reason": "rain"}
    result = compute_laytime(
        basis(
            {"laytime_basis": "SHEX"},
            [port(completed="2026-03-09T08:00",
                  allowed={"kind": "fixed_days", "days": "1"},
                  interruptions=[rain_after])],
        )
    )
    assert result["ports"][0]["demurrage_start"] == "2026-03-03T08:00"
    assert result["demurrage_days"] == "6.00000"
    assert result["demurrage_amount"] == "48000.00"

Laytime 2 Mart Pazartesi 08:00'de başlar, bir gün izin verilmiştir, dolayısıyla demuraj 3 Mart Salı 08:00'de başlar. Yük ertesi Pazartesi tamamlanır. Bu iki an arasında altı saatlik bir yağmur duruşu ve tam bir pazar günü vardır. SHEX altında ikisi de demurajdan önce düşülürdü; sonrasında ikisi de düşülmez. Günlüğü 8.000'den altı tam gün: 48.000. Bir insan bunun her satırını bir takvim ve bir kalemle kontrol edebilir.

Eş test aynı yağmur duruşunu demuraj başlamadan önceye taşır ve şimdi demuraj başlangıcını altı saat kaydırdığını ve faturayı 46.000'e düşürdüğünü doğrular. Üçüncü bir test çarter partinin istisna bayrağını çevirir ve yağmurun demurajdan sonra da düşüldüğünü gösterir. Üç test; bir kural ve iki kenarı.

"Beklenen değeri asla güncelleme" neden asıl mesele

Bir test takımının olağan hayatı: bir refactor bir çıktıyı değiştirir, test başarısız olur, geliştirici yeni çıktıya bakar, iyi görünüyor der ve doğrulamayı günceller. Çoğu kod için bu makuldür. Bu kod içinse tam olarak önlemeye çalıştığımız hatadır.

Bir motor değişikliği 48.000'i 46.000'e çevirir ve biri testi güncellerse, üzerinde 48.000 yazan ve çoktan gönderilmiş her statement artık ofisin kendi yazılımıyla çelişir. Karşı tarafın avukatı bunu bulur.

Bu yüzden politika asimetriktir. Bir altın testin başarısız olması iki şeyden birini gösterir:

motor yanlıştır ve test geçene kadar kod düzeltilir, ya da
kuralın kendisi değişmiştir; bu durumda eski test eski kural altında (dayanakta bir bayrağa dönüşür) sayısını korur ve yeni kural altında elle doğrulanmış yeni bir sayıyla yeni bir test eklenir.

İki durumda da mevcut bir dayanak mevcut sonucuna yeniden oynatılır. Eski statement'lar doğru kalır. Dayanak kuralı taşır; böylece eski ve yeni bir arada var olabilir.

Kurallar ne olmak zorundaydı

Elle doğrulanabilir örneklere ulaşmak, her kuralı koddaki bir varsayım yerine dayanakta açık bir alan yapmaya zorladı bizi. Hayatta kalan küme:

SHINC her şeyi sayar; SHEX ve WWD pazarları ve bir tatil listesini atlar. Hava durumu çıkarsanmaz; bir hava duruşu bir kesinti kaydıdır. Dolayısıyla WWD ve SHEX motor için aynıdır; fark ofisin ne kaydettiğindedir.
unless_used: istisna günleri yine de sayılır ve o günlerdeki boş zaman diğerleri gibi kesinti kayıtlarıyla düşülür.
nor_to_start_hours: NOR kabulü ile sayımın başlangıcı arasındaki boşluk.
İzin verilen süre sabit gün olarak ya da yük miktarının günlük orana bölümü olarak.
Yarım ya da tam dispeç; kazanılan çalışma zamanı ya da kazanılan tüm zaman üzerinden. İkincisi SHEX altında ince olanıdır: kullanılmayan iznin ne zaman biteceğini bulmak için, pazarlar dahil takvime yansıtılması gerekir. Aynı iki gün erkenliğin çalışma zamanında dört, tüm zamanda beş gün ettiği bir altın test var.
Reversible laytime: limanlar arasında tek bir havuz defteri; yüklemede kazanılan zaman tahliyeye taşınır. Test, aynı iki liman uğrağının havuzlandığında yarım gün demuraj, ayrı ayrı hesaplandığında bir buçuk gün demuraj artı bir gün dispeç verdiğini gösterir. Aynı olgular, iki sayı, ikisi de kendi maddesi altında doğru.
Demuraja bir kez girildi mi hep demurajda; aksini söyleyen çarter partiler için açık bir vazgeçme bayrağıyla.

Diğer her şey, özellikle çarter parti metninin yorumlanması ve Statement of Facts'in ayrıştırılması, bilinçli olarak fonksiyonun dışındadır. Motor olguları ve kuralları alır; olguların ne olduğuna karar vermek insanın işidir.

Testleri mümkün kılan iki uygulama tercihi

Tam saniye ve Decimal. Zaman tam sayı saniye olarak sayılır ve yalnızca çıktı için, yarım yukarı yuvarlanmış beş ondalıklı bir dize olarak güne çevrilir. Para, günlük orandan saniye oranıyla hesaplanan iki basamaklı Decimal'dır. Hiçbir şey float değildir; dolayısıyla 0,1 artı 0,2 hiç görünmez ve bir sonuç, bir insanın yazdığı dizeyle == ile karşılaştırılabilir.

Aralıklar sayımdan önce birleştirilir. Kesintiler ve istisna günleri, liman yerel zaman çizelgesi üzerinde aralıklardır. Laytime penceresine kırpılır, birleştirilir ve sayılabilir zaman geriye kalandır. Bu yüzden bir pazarla çakışan yağmur duruşu iki kez düşülmez ve dağınık bir SOF'tan gelen çakışan kesinti kayıtları kesintiyi şişirmez. Birleştirme birkaç satırdır ve tablolardaki elle hesap hatalarının çoğu tam buradan gelir.

Motoru açık kaynak yapmak

Motorun bağımlılığı yoktur ve durum okumaz; bu yüzden onu MIT lisansı altında bağımsız bir paket olarak çıkardık: laytime. Altın testler değişmeden onunla gitti.

Gerekçe, saklanan dayanaktakiyle aynı. Bir laytime statement'ı başkasına karşı bir taleptir. O başkası paketi kurabiliyor, statement'ta basılı dayanağı ona verebiliyor ve aynı sayıyı alabiliyorsa statement zayıflamaz, güçlenir. Pazarların nasıl atlandığında tescilli bir şey yoktur; ürünün değeri olguları hızla yakalamakta ve saklamaktadır.

pip install laytime
laytime basis.json

Küçük bir ofise ne söylerdik

Dayanağı saklayın. Hangi aracı kullanırsanız kullanın, bir statement'ı üreten girdi değiştirilmeden statement'ın yanında saklanmalı. Yeniden oynatabiliyorsanız savunabilirsiniz. Aracınız kullandığı girdinin tam halini gösteremiyorsa o bir hesap makinesi değil, bir görüştür.

Motor: github.com/oktaybobus/laytime. MarOps vaka çalışması: zdeck.tech/case-study-marops.html.