DEV Community: Shipmind Labs

A discount has a VAT rate: EN 16931 totals from the bottom up

Shipmind Labs — Thu, 17 Sep 2026 13:27:52 +0000

An invoice carrying a discount is the easiest way to produce a document that agrees with itself and is wrong anyway. The lines add up, the totals agree with the lines, and every arithmetic rule on the totals passes. The VAT breakdown is still wrong, because a document level allowance belongs to a VAT category and a rate rather than to the invoice as a whole, and it moves the taxable amount of exactly one breakdown group.

From 2026 that stops being a bookkeeping quibble. A rejected invoice used to be an email nobody answered. Now it is a document a government platform refuses. Belgium requires Peppol from January 2026, Poland's KSeF clears every invoice before it counts as delivered, and from September 2026 every business in France must be able to receive one. Under a clearance model an invoice that fails validation was not issued at all, so there is no unpaid invoice to chase, because as far as the platform is concerned nothing was sent. Failing at your own desk, with a message naming the rule and the element, beats failing at theirs.

We build payment and billing systems for a living (ledgering, attribution, reconciliation between what a system thinks it charged and what actually moved), and this failure mode is an old one in new clothes: a total that came from a different version of the document. What is new is the referee. So we wrote the checks down as a library, invoicerules (https://github.com/shipmindlabs/invoicerules), and made the write path depend on them.

An allowance on a line and an allowance on the document are different animals

EN 16931 has both, and the difference between them is what this whole article is about.

A line level allowance or charge (BG-27 / BG-28) carries no VAT category of its own. It belongs to the line, follows the line's category and rate, and is taken off or added on before the line net amount that the totals and the breakdown are built from:

export type LineAllowanceCharge = {
  /** BT-136 / BT-141: the amount, always positive. */
  readonly amount: Amount;
  /** BT-137 / BT-142: the amount a percentage applies to. */
  readonly baseAmount?: Amount;
  /** BT-138 / BT-143: percentage of the base amount. */
  readonly percentage?: string;
  /** BT-139 / BT-144: why it is on the line. */
  readonly reason?: string;
};

A document level allowance or charge (BG-20 / BG-21) does carry one, and has to:

export type AllowanceCharge = {
  /** BT-92 / BT-99: the amount. */
  readonly amount: Amount;
  /** BT-95 / BT-102: the VAT category it belongs to. */
  readonly vatCategory: VatCategory;
  /** BT-96 / BT-103: the VAT rate it belongs to. */
  readonly vatRate: string;
  /** BT-97 / BT-104: why it is on the invoice. */
  readonly reason?: string;
};

Two things follow from the types alone. The amount is positive in both cases, and the list it sits in decides whether it gets subtracted or added, so there is no sign convention to get wrong and no negative amount to slip past a check. The second is that a document level discount cannot be modelled as "a discount on the invoice", because the category and the rate are required fields, and a discount that belongs to no breakdown group does not exist.

The group is computed, then compared

Take an invoice with two lines at two rates and one discount that was negotiated against the larger of them.

const lines = [
  { id: "1", name: "Integration work", quantity: 1, netPrice: "1000.00",
    netAmount: "1000.00", vatCategory: "S", vatRate: "23" },
  { id: "2", name: "Printed handbook", quantity: 10, netPrice: "20.00",
    netAmount: "200.00", vatCategory: "S", vatRate: "5" },
];

const allowances = [
  { amount: "100.00", vatCategory: "S", vatRate: "23", reason: "Volume discount" },
];

Done correctly, the breakdown has two groups: category S at 23 percent with a taxable amount of 900.00 and VAT of 207.00, and category S at 5 percent with 200.00 and 10.00. Total without VAT 1100.00, total VAT 217.00, total with VAT 1317.00.

Now the common wrong version, the one that falls out of a system where the discount is a field on the order rather than a member of a VAT group. The lines are reported at 1000.00 and 200.00, the VAT on them is 230.00 and 10.00, the discount is subtracted from the net total, and the document declares 1100.00 without VAT, 240.00 of VAT, 1340.00 with it.

Run the totals rules over that invoice and they all pass. The line total matches the sum of the lines (BR-CO-10). The allowance total matches the document allowances (BR-CO-11). The total without VAT is the line total less allowances plus charges (BR-CO-13). The declared VAT equals the sum of the breakdown groups (BR-CO-14). The total with VAT is the sum of the two (BR-CO-15), and the amount due matches it (BR-CO-16). The document is internally consistent to the cent, and it charges the buyer 23.00 of VAT that is not due.

The only check that catches it is the one that rebuilds each group from the lines and from the document level allowances and charges attributed to that group, then compares the result with what the document declares. That is why the breakdown is computed rather than summarised:

import { computeVatBreakdown, reconcile } from "invoicerules";

computeVatBreakdown(invoice); // subtotals per category and rate, VAT rounded to the cent
reconcile(invoice);           // every arithmetic check, passing or not

reconcile returns each check with the rule it comes from and the business term it constrains (BR-CO-13 against BT-109), so you can display an amount together with the rule it answers to, not only with whatever failed.

A failure is a place, not a boolean

A red cross on its own teaches an engineer nothing. The output worth building is the pair (rule id, element path), and the path has to be the one the document will have on the wire, not the one your model uses:

import { validate, toUBL } from "invoicerules";

const result = validate(invoice);
if (!result.ok) {
  for (const v of result.fatal) console.error(`${v.rule} at ${v.path ?? v.at}: ${v.message}`);
}

Every evaluated rule also comes back in a coverage report, naming the element both as the model field and as its position in the document that gets sent:

validate(invoice).coverage.find((c) => c.rule === "BR-CO-16");
// { rule: "BR-CO-16", outcome: "fail",
//   at: "totals.payable", path: "/Invoice/LegalMonetaryTotal/PayableAmount",
//   message: "the amount due 330.00 does not match the total with VAT 300.00" }

Rules that run against several elements are reported against each one, so a line with no breakdown group shows up as /Invoice/InvoiceLine[3]/Item/ClassifiedTaxCategory/ID rather than as the invoice in general. A rule with nothing to check (there is no seller VAT identifier, so there is no prefix to test) is absent from the report instead of being counted as a pass. That distinction is what makes the report readable as evidence, because it tells you what was actually looked at.

The rule identifiers are the standard's own, deliberately. BR-CO-15 reads as noise until a platform quotes it back at you, and keeping it means an error from our library and an error from the receiving end name the same thing. The wording of each message is ours. The normative text lives in EN 16931-1, published by CEN, and is not reproduced.

Cents, and why floats lose them

Money is not a float. 0.1 + 0.2 is how a totals check fails on an invoice that is perfectly correct, and rounding VAT in binary floating point produces exactly the cent of difference a validator rejects. Every amount is held as an integer and a scale with half-up rounding, which is also why the model types amounts as strings rather than numbers. A number literal in a JSON payload has already lost the argument.

One cent of rounding difference on a total is tolerated, because with per-group rounding it is normal and the standard expects it. Two is not. Fixing this at the type level costs a small decimal module and a test file, while discovering it from a rejection notice costs a day and somebody's trust in the billing system.

The writer refuses

Validation that a caller can skip under deadline is not validation. Serialisation is where we put the gate:

const xml = toUBL(invoice); // throws unless the rules pass

There is no flag to force it. If the document has fatal violations there is no correct XML to produce, and producing it anyway only moves the failure to a place with slower feedback and an audit trail attached.

What it costs to run

Less than you would guess, because there is nothing to operate. The checks are pure functions over a model, with no network call, no service to deploy and no queue. It runs in a unit test, in a pre-submit check, and in the request that draws the invoice preview, and it answers the same way in all three.

The cost that is real is the rule set itself. Rules get clarified, countries add their own layer on top of the European core, and each of those is a change to a list you can read rather than a change to a condition buried in a serialiser. The coverage report is the maintenance surface, since it tells you which rules ran, so adding one is visible and losing one is visible too. Two things stay deliberately out of scope. It is not an access point, because writing the document and getting it to the receiver are different jobs, the second one with registration and certificates attached. It also does not read UBL. Node has no XML parser in its standard library, so a reader means either a dependency or a hand-rolled parser, and a hand-rolled XML parser is probably a security bug with a release schedule.

Close

Use the discount as your test case. If the VAT breakdown in your system is a summary of the lines, the invoice will satisfy every check you wrote, pass through your own review, and get refused by a platform that recomputed the groups. Under clearance, the difference between finding out at your desk and finding out at theirs is the difference between an edit and an invoice that never existed.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.

Why a six-digit code is safe: entropy, attempts and the pepper

Shipmind Labs — Sun, 13 Sep 2026 13:21:43 +0000

A six-digit numeric code carries 19.93 bits of entropy, a number no password policy would accept. It is still the correct primitive for passwordless login and step-up confirmation, but only because two other mechanisms carry most of the guarantee: a bounded attempt budget, and a stored digest that cannot be ground down offline. When those two live in whichever request handler happened to need them, the safety of the code stops being a property of the system and becomes a property of the last person who edited the handler.

We extracted this reasoning into a small library, otpguard (https://github.com/shipmindlabs/otpguard), after building the same flow more than once across payment confirmation, KYC re-verification and account recovery. It is early development and the public API is not stable yet, but the shape of the problem is settled, and the shape is the interesting part.

The arithmetic nobody writes down

The security of a one-time code is not the entropy of the code. It is the entropy divided by the number of guesses an attacker is allowed against it. The library makes the first half of that fraction explicit:

from otpguard import DIGITS, UPPERCASE_UNAMBIGUOUS, CodePolicy

CodePolicy(length=6, alphabet=DIGITS).entropy_bits                  # 19.93
CodePolicy(length=8, alphabet=UPPERCASE_UNAMBIGUOUS).entropy_bits   # 39.2

Six digits is one million possibilities. Five allowed attempts against a single issued code is a five-in-a-million chance of a hit. That is a perfectly reasonable number for confirming a transfer, and it holds only as long as the five is real.

Notice which lever is cheap. Adding two characters to the code is expensive: users retype it from a message, read it aloud on a support call, mistype it more often, and ask for another one. Lowering the attempt ceiling from twenty to five costs nothing and moves the same fraction by a factor of four. The attempt ceiling is the lever that actually protects the flow, and it is the one that is usually implemented as an integer comparison somewhere in a view function.

The budget is state, which is why it belongs in the machine

An attempt ceiling is not a constant. It is a counter, a lockout deadline and a resend cooldown, all of which are written and read concurrently, and all of which have to survive being reached from more than one entry point. A code confirmed in a mobile app, on the web and by a support operator re-triggering delivery is the same code with the same budget.

The resend cooldown is the part that gets misread most often. It looks like politeness about message cost. It is not — it is what stops the attempt budget from being refilled on demand. If the attempt counter is scoped to the pending code rather than to the identity and the purpose behind it, then requesting a fresh code resets the counter, and an attacker with an unbounded resend button has an unbounded number of attempts against a twenty-bit space. The cooldown and the counter are two views of one budget, which is exactly why they cannot be two separate features owned by two separate call sites.

In otpguard the cooldown is authoritative about the rule and deliberately holds no state itself. The caller stores the moment of the last delivery next to the pending code, in their own table, inside their own transaction, and passes it back:

from datetime import datetime, timedelta, timezone
from otpguard import ResendCooldown, ResendTooSoon

cooldown = ResendCooldown(timedelta(seconds=60))

try:
    cooldown.check(last_sent_at)        # None on the first request
except ResendTooSoon as exc:
    exc.retry_after                     # timedelta(seconds=43)
    exc.retry_after_seconds             # 43.0, ready for a Retry-After header
else:
    send(generate_code())
    last_sent_at = datetime.now(timezone.utc)

The refusal carries the remaining interval, so the HTTP layer does not recompute it and cannot disagree with the library about when the next code is allowed. retry_after() returns the same remaining time without raising, allows() answers with a bool, and next_allowed_at() gives the absolute moment — three shapes of one decision, so no caller has to derive it from a timestamp difference and get the sign wrong.

This is also the reason the library does not own a table. The decisions are pure; the row belongs to the application. That keeps the transition committable inside whatever transaction the caller already has open, and it means the invariants can be tested without a database, a broker or a clock.

Delivery is the one thing that genuinely varies. SMS, email and messenger fan-out sit behind the same request-verify flow, and we have built multi-channel notification services often enough to know how much variety hides there. None of that variety is allowed to reach the budget.

An offline attacker has no attempt budget at all

Everything above assumes the attacker is online, spending attempts against your endpoint. If the table leaks, that assumption is gone, and a million HMAC evaluations is a rounding error of CPU time. Twenty bits protects nothing offline.

So the stored form has to be a digest, salted, and — if you want the online requirement back — bound to a secret that does not live in the database:

from otpguard import generate_code, hash_code, verify_code

code = generate_code()                  # '482913'
stored = hash_code(code, pepper=SERVER_SECRET).encode()

verify_code(candidate, stored, pepper=SERVER_SECRET)

The clear-text code exists only long enough to be delivered. A fresh salt is drawn on every hash, so the same code never produces the same digest twice and the table shows no collisions to sort by. Comparison goes through hmac.compare_digest, so verification does not leak position information through timing. The stored string carries its algorithm — hmac-sha256$<salt>$<digest> — and a digest tagged with anything else never verifies rather than falling back to something older.

The pepper is what restores the arithmetic after a dump: without the secret, the offline attacker is back to being an online one.

The code you send and the code the user types are different strings

Users paste codes with spaces, hyphens and stray case. Support operators read them over the phone. CodePolicy owns that normalization, and both hashing and verification run through the same normalize, so the two sides cannot drift:

policy = CodePolicy(length=6, alphabet=UPPERCASE_UNAMBIGUOUS)
hashed = hash_code("AB2CD3", policy)

verify_code("ab2-cd3", hashed, policy)     # True
verify_code(" AB2 CD3 ", hashed, policy)   # True

The bundled UPPERCASE_UNAMBIGUOUS alphabet drops the characters that are easy to confuse when a code is read aloud — 0 and O, 1 and I, 5 and S. This looks like a usability detail, and it is one, but it feeds straight back into the budget: every code a user cannot retype correctly is a resend, and resends are the pressure that makes teams raise the ceiling.

Case folding also has a cost, and the policy refuses to let you hide it. An alphabet containing both a and A is rejected for a case-insensitive policy, because the two characters are the same character once input is folded, and entropy_bits would otherwise report a number the system does not actually deliver. Codes shorter than four characters and alphabets that overlap the separator set are rejected for the same reason: a configuration whose entropy claim is a lie should fail at construction, not in an incident review.

What it costs to run

One row per pending code: the encoded digest, the purpose it was issued for, the moment of last delivery, an attempt count and a lockout deadline. One write per transition, all of them in the caller's own transaction. No extra infrastructure — no cache tier, no broker, nothing that can be up while the database is down and disagree with it afterwards.

The pepper is the one operational commitment. A peppered digest verifies only under the same pepper, so rotating it invalidates every code minted under the old one. With a code lifetime measured in minutes that is a non-event, provided you know it before you rotate rather than after.

None of this is difficult. It is simply arithmetic that has to be owned somewhere, and a request handler is not somewhere. The code is the smallest part of a one-time code; the budget around it is the product.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.

A notification template is a contract, not a string

Shipmind Labs — Sat, 12 Sep 2026 13:22:19 +0000

A notification is one of the few outputs in a production system with no undo. Once a provider accepts the payload, the SMS is on a phone, the email is in an inbox, and the push has already lit a lock screen. Yet the body of that message is usually the least-checked value in the codebase: a format string in a module constant, filled from a dictionary assembled three call frames away, with nothing between the two but the assumption that whoever wrote the call site read the string carefully.

We build notification layers often — order confirmations on cross-border commerce platforms, reminders and warnings in a lending product's collections flow, verification outcomes for compliance teams, fan-out from one service to mobile push, SMS, WhatsApp and Telegram. The recurring defect is almost never the transport. Providers are boring: they accept the message or they return an error you can classify and retry. The expensive defect is the message that was delivered successfully and was wrong.

So the question we keep coming back to is not how to send reliably. It is where a notification's contract lives, and what checks it.

The format string promises nothing

A Python format string is permissive in one direction and fatal in the other, and both behaviours land at send time.

TEXT = "Order {order_id} confirmed: {item_count} item(s), total {total:.2f}."

TEXT.format(order_id="A-1042", item_count=3, total=59.9, coupon="SPRING")
# 'Order A-1042 confirmed: 3 item(s), total 59.90.'  — coupon silently ignored

TEXT.format(order_id="A-1042", item_count=3)
# KeyError: 'total'

TEXT.format(order_id="A-1042", item_count=3, total="59.90")
# ValueError: Unknown format code 'f' for object of type 'str'

Three different outcomes for three different call-site mistakes, and not one of them is a check. The extra key is a typo that will never be reported: someone renamed coupon_code to coupon in the template, missed the call site, and the discount line quietly stopped appearing. The missing key is a KeyError raised at the moment of handover. The wrong type is a ValueError from the formatting machinery, phrased in terms of format codes rather than in terms of the variable that was wrong.

The timing is what makes this costly. Notification delivery is backgrounded in every serious system — you do not hold an HTTP request open while a provider decides whether it likes a phone number. That means the exception does not surface in the request that caused it. It surfaces in a worker, detached from the input that produced it, in a log line nobody is watching, while the customer who was supposed to receive the confirmation receives nothing at all. If the failure mode is the permissive one instead, there is no log line to miss, because nothing failed. The message went out with a gap in it.

The declaration is the other half of the contract

A template has two sides that can disagree: the text, and the set of values the text needs. A bare string carries only one of them, so the other side lives in the heads of the people writing call sites. That is the whole bug.

We wrote notify-dispatch (https://github.com/shipmindlabs/notify-dispatch) around the opposite premise: a template declares the variables it needs and the type of each one, and that declaration is checked against the text at construction time.

from notify_dispatch import Template, Variable

confirmation = Template(
    name="order_confirmed",
    text="Order {order_id} confirmed: {item_count} item(s), total {total:.2f}.",
    variables=(
        Variable("order_id", str),
        Variable("item_count", int),
        Variable("total", float),
    ),
)

The duplication here is deliberate and it is the point. The text and the variable tuple are two independent statements of the same requirement, so they can be compared. An undeclared {placeholder} in the text, or a declared variable the text never uses, raises TemplateDefinitionError when the Template is constructed — not when it is rendered, and not when it is sent. Declare your templates at module level in a module your application imports at startup, and a template that contradicts itself stops the process instead of shipping.

At render time the contract is enforced against the values:

confirmation.render({"order_id": "A-1042", "item_count": 3, "total": 59.9})
# 'Order A-1042 confirmed: 3 item(s), total 59.90.'

confirmation.render({"order_id": "A-1042", "item_count": 3})
# MissingVariableError: template 'order_confirmed' is missing values for: total

confirmation.render({"order_id": "A-1042", "item_count": "3", "total": 59.9})
# VariableTypeError

confirmation.render({**context, "coupon": "SPRING"})
# UnknownVariableError

Three named errors instead of a KeyError, a ValueError and a shrug. The one that earns its keep in practice is UnknownVariableError, because it converts the silent failure into a loud one. The renamed variable that used to vanish without trace now stops the send.

Types matter here for a reason beyond tidiness. {total:.2f} is a formatting instruction that only works on numbers, and money in a notification is exactly the value you least want rendered by accident. Declaring Variable("total", float) moves that from an incident inside str.format to a rejection with the variable's name attached.

Validation belongs before the handover, not around it

A contract that is checked inside the provider call is not much better than no contract. The ordering is the invariant: rendering and validation must complete before anything irreversible happens, because the handover to a provider is the step you cannot take back.

One dispatch call renders the template and then delivers it, in that order, with provider adapters per channel behind a single protocol:

receipt = dispatcher.send(
    Recipient(phone="+49151000000", email="ada@example.com"),
    confirmation,
    {"order_id": "A-1042", "item_count": 3, "total": 59.9},
)

And the guarantee is a test, not a claim in a docstring:

def test_template_errors_surface_before_any_provider_is_called():
    sms = Provider()
    dispatcher = Dispatcher([SmsAdapter(sms)])

    with pytest.raises(MissingVariableError):
        dispatcher.send(Recipient(phone="+491"), ORDER_CONFIRMED, {})
    assert not sms.calls

The second assertion is the one we care about. pytest.raises proves the error happens; assert not sms.calls proves it happens early enough. Any refactor that moves validation after the adapter lookup, or that renders lazily inside the delivery path, breaks that line. This is the kind of test we want in a review gate: it does not check behaviour, it checks an ordering that a future contributor would otherwise have no way of knowing was load-bearing.

Two error classes, two operational responses

Once the contract is explicit, notification failures split cleanly, and the split is what makes the runtime tractable.

Contract violations — TemplateDefinitionError, MissingVariableError, UnknownVariableError, VariableTypeError — are bugs in our code. They are deterministic, they will fail identically on every attempt, and retrying them is pure waste. They should surface at import, in tests, or at the top of dispatch, and they should never be retried or parked.

Delivery failures are environmental. A provider is down, a token is stale, an address is rejected. These are the failures worth a RetryPolicy with a growing backoff and a retry_on list, and worth wrapping in DeliveryError carrying the channel and address so the log line says which of three providers actually broke. What still fails after the last attempt lands in dispatcher.dead_letters with every attempt that was made, so a lost notification is something you can list and hand to whoever replays it, rather than a line someone has to find in a worker log.

The useful consequence: nothing in the dead-letter queue is ever a template bug. A queue that mixes "the SMS gateway was unreachable for ninety seconds" with "we forgot to pass total" is a queue nobody drains, because half of it is unreplayable by construction. Keeping contract violations out of it is what makes the remainder worth looking at.

What it costs

The cost is the declaration. Every template is a few lines longer than the string it replaces, and adding a variable means touching the text and the tuple. In exchange, the pair checks itself at construction, so the duplication cannot drift — which is the opposite trade from a comment describing which keys a format string expects.

The other cost is discipline about where templates are constructed. The construction-time check only protects you if the constructors run. Templates defined at module import in a module the application and the test suite both load get checked on every process start and every CI run. Templates built inside the function that sends them get checked only when that path executes, which puts you back where you started, with the rarely-exercised notification as the one that breaks.

A missing order_id costs nothing to fix in a test, a few minutes in CI, and an apology in production. The only variable in that sentence is where you choose to find it.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.

Overlapping delivery zones resolve by explicit priority

Shipmind Labs — Fri, 11 Sep 2026 13:22:19 +0000

Two zones covering the same street is normal: a city hub reaches it, and the store's own ring reaches it too. The overlap is fine. What goes wrong is the resolution, because most implementations return the first polygon a loop matched, which quietly promotes the order rows came out of a file into a business rule nobody wrote down and nobody can test.

We keep meeting this shape in delivery work: dark-store marketplaces with role-specific apps for couriers, warehouse staff and store operations, and cross-border commerce where the carrier and the fee follow from the address. The part that never changes we pulled into a small library of our own, delivery-zones (https://github.com/shipmindlabs/delivery-zones). The rule it enforces is what this post is about: an overlap has to be a modelled decision, and the model is a priority a reader can find.

Insertion order is a rule you did not write

The honest primitive is a lookup that returns everything. You ask which zones reach an address and you get every match, in the order the zones were given. That is the truth about the catalogue, and it is also where the bug starts, because the call site is usually matches[0].

Once that index exists in application code, the loader owns dispatch. Someone edits a zone and re-saves it, so it moves to the end of the file, and the fee tier for one street changes with no diff in any rule. Or a staging catalogue gets seeded in a different order than production, so the two environments route the same address to different stores and both look correct in isolation. Nothing raises. Nothing is logged. The failure is a customer paying the wrong delivery fee, and the code review that would have caught it never saw a line worth questioning.

Sorting the matches inside the lookup does not fix this, it only moves the implicit rule one level down. The fix is that the zone carries the rank, and the caller names the policy that uses it.

A zone is a polygon plus the metadata a caller acts on

Zones are read from GeoJSON features and held in memory, so no database is involved. Each one carries what a dispatcher actually asks about an address: which store serves it, what tier the delivery falls into, when the area accepts orders, and how it ranks against its neighbours.

from datetime import datetime

from delivery_zones import Zone

zone = Zone.from_geojson(
    {
        "type": "Feature",
        "id": "downtown",
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    [13.37, 52.51],
                    [13.42, 52.51],
                    [13.42, 52.54],
                    [13.37, 52.54],
                    [13.37, 52.51],
                ]
            ],
        },
        "properties": {
            "store_id": "store-1",
            "fee_tier": "standard",
            "priority": 10,
            "store_location": [13.39, 52.52],
            "service_hours": [
                {"weekday": "mon", "opens": "09:00", "closes": "21:00"}
            ],
        },
    }
)

zone.priority                                    # 10, or 0 when undeclared
zone.is_open_at(datetime(2026, 8, 24, 10, 0))    # True, a Monday morning

The default matters more than it looks. A zone that declares nothing sits at priority 0, so a catalogue that has never thought about overlaps behaves as a flat set of equals, and equals are ambiguous rather than silently ordered. The absence of a decision stays visible instead of being papered over by whichever zone happened to be parsed first.

The ranking is an argument, and the tie is a different argument

Which zone wins is a business rule, so it belongs at the call site, spelled out:

from delivery_zones import TieBreak, ZoneIndex, by_priority, by_smallest_area

index = ZoneIndex.from_geojson(feature_collection)

index.zones_containing(address)                                    # every match
index.zones_containing(address, policy=by_priority(TieBreak.RAISE))
index.zones_containing(address, policy=by_smallest_area(TieBreak.FIRST))

Two rankings cover most catalogues. by_priority ranks on the zone's declared priority, higher first, which is what you want when the hierarchy is commercial, like a promoted hub that should take a district off the neighbouring stores. by_smallest_area prefers the tightest coverage, usually the most specific zone, and that fits when the hierarchy is geographic and nobody wants to maintain numbers by hand.

The second argument is the one we care about most, because it is the one every home-grown implementation gets wrong by omission. How you rank and what you do when the leaders rank equally are separate questions, so the tie-break is required rather than defaulted. TieBreak.FIRST keeps the first zone in declaration order, still insertion order, but now it is a choice somebody typed. TieBreak.ALL returns every leader and hands the decision back to the caller, which is what you want when the answer can legitimately be two stores. TieBreak.RAISE raises AmbiguousCoverage, so a bad catalogue surfaces instead of routing at random.

We deliberately ship no default here. A default tie-break is the same bug as insertion order, only harder to see, because it has a respectable name.

A policy is a callable, so your rule fits the same slot

Ranking by priority or area does not exhaust what "who serves this address" means. A policy is just a callable from matched zones to chosen ones, and every policy returns a tuple, empty when nothing covers the address. So a rule of your own drops into the same argument:

from datetime import datetime


def open_at(moment):
    def policy(zones):
        return tuple(zone for zone in zones if zone.is_open_at(moment))

    return policy


index.zones_containing(address, policy=open_at(datetime(2026, 8, 24, 10, 0)))

Zones without declared service hours count as open, so a catalogue that says nothing about hours does not collapse to empty coverage the first time someone uses this. When the rule is "highest or lowest something", ranked_by builds the policy out of any measure of a zone, and the tie question comes along with it.

Worth noticing: composing two rules is itself a decision. Filtering to the open zones and then ranking gives a different answer than ranking and then filtering. In the first, the city hub takes over the street when the local store closes. In the second, the street simply has no coverage at 22:00. Both are defensible, and neither should be an emergent property of the order two helpers were called in. Put the composition inside one named policy so it is one thing with one test.

The overlaps you can see and the holes you cannot

Overlap resolution and coverage gaps are two halves of the same question, which zone serves this point, and whether any zone does. An overlap shows up the moment you look at a lookup result. A gap shows up when an order fails. A scan walks a lattice over the served area, asks the index about every position and groups the misses:

from delivery_zones import scan_coverage

report = scan_coverage(index, spacing=0.002)

assert report.is_complete, report.describe()

report.gaps[0].size              # how many sampled positions this gap holds
report.gaps[0].representative    # a position inside it, ready to paste into a bug
report.gaps[0].bbox              # where to look on a map

That assertion belongs in the catalogue's own test suite, next to the priority assertions. A strip between two rings, or a hole cut around a lake, then fails a test run instead of an order. spacing decides what the scan can see: a gap narrower than the lattice slips between samples, while a fine spacing over a whole city costs many lookups, which is why the scan refuses more than a million positions. A sample landing exactly on a border may fall either way, so it is probably worth choosing a spacing that does not align with your rings. By default the scan covers the envelope of the indexed zones, and passing an explicit bounding box is how you check a district the catalogue is supposed to reach but may have forgotten entirely.

What it costs to run

The index prepares the polygons once and buckets them into a grid, so a lookup does not walk the whole catalogue. Everything is in memory and read from GeoJSON, which makes the catalogue a deploy artifact: cheap at request time, and reloaded when it changes rather than queried.

The recurring cost is editorial, not computational. Someone has to own the priority numbers, and leaving gaps between them makes inserting a zone later an edit to one feature rather than a renumbering. Our own split is to run the strict tie-break in the catalogue's test suite, where AmbiguousCoverage is a build failure and a named engineer fixes the feature, and a ranked policy in dispatch, where a request needs an answer. Ambiguity then becomes something the catalogue owner resolves on a Tuesday afternoon, not something dispatch improvises at peak hours.

The library is pre-alpha and the public API is not stable yet. The rule underneath it holds anyway: if two zones cover the same address, either the catalogue says which one wins, or the code says it does not know. Insertion order is not a third option, it is the first one, written by accident.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.

An accessibility statement your audit trail can support

Shipmind Labs — Thu, 10 Sep 2026 13:26:07 +0000

An accessibility statement is a public compliance claim, and in most organisations it is produced the way a summary gets produced: someone reads the last audit report, forms an impression, and picks one of the three statuses the European model statement allows. The evidence and the claim are joined by a person's memory of a spreadsheet, which is precisely the joint that fails when a regulator asks what was checked, by whom, when, and on which build.

We build compliance tooling as a large part of our work — verification and moderation screens for compliance teams, e-signature and document workflows, decision trails that have to survive being questioned later. The shape of the problem is always the same: an artefact that asserts something must be derivable from a record, or it is only a sentence. Accessibility is a good place to show the mechanics, because the distance between what tools measure and what the document claims is unusually wide. Automated tooling settles roughly a quarter to a third of WCAG. The rest is judgement — whether alt text describes the picture, whether the focus order makes sense, whether an error message tells anyone what to do. So the statement is mostly a claim about human work, and human work leaves no trace unless you build one.

We put ours into a small TypeScript library, a11ytrail (https://github.com/shipmindlabs/a11ytrail). It runs no tests: axe-core, Playwright and a person with a screen reader do that. It consumes what they produce, keeps the record, and derives what may be claimed from it.

The unit of evidence is a check, not a criterion

The first modelling decision is what a row means. The intuitive answer — one row per success criterion, holding pass or fail — is wrong, and it is wrong in a way that costs you the audit. A criterion is not checked in the abstract; it is checked on something, by someone, at a moment, against a build. Drop any of those and the row stops supporting the claim you want to make with it.

import { Evidence } from "a11ytrail";

const evidence = new Evidence()
  .add({
    criterion: "2.4.7",
    outcome: "passed",
    method: "manual",
    checkedAt: "2026-07-14",
    checkedBy: "audit team",
    scope: "home",
    build: "2026.07.1",
  })
  .add({
    criterion: "2.4.7",
    outcome: "failed",
    method: "assistive-technology",
    checkedAt: "2026-08-05",
    checkedBy: "audit team",
    scope: "checkout",
    note: "focus ring is removed on the payment step",
  });

evidence.latestPerScope("2.4.7");
// one check per scope: home passed, checkout failed

Two properties follow from that shape, and both matter more than they look.

The collection is append-only. A recorded check is copied and frozen, and the list handed back is a copy. Correcting a check means recording a later one — which is also exactly what re-testing after a fix looks like, so the two operations need no separate code path. The earlier result stays in the trail, because an audit asks what you knew and when, not what you believe now.

And later supersedes earlier per scope, never across scopes. That is what latestPerScope encodes. A pass on the home page does not speak for checkout; if it did, the cheapest way to become compliant would be to test the simplest page twice. We have shipped enough moderation and review tooling to know that the aggregate is where the lie enters — one green number over rows that were never comparable.

Anonymous evidence is not evidence

Validation on write is where most of the discipline lives, because the cost of a bad row is paid months later by someone who cannot tell it is bad. A check that names no one, names no scope, or carries an unreadable date is rejected at add. So is an automated result that does not name the tool:

evidence.add({
  criterion: "1.4.3",
  outcome: "passed",
  method: "automated",
  checkedAt: "2026-08-05",
  checkedBy: "ci",
  scope: "checkout",
});
// InvalidCheck: automated check for 1.4.3 does not name the tool:
// a result nobody can reproduce is not evidence

The outcome enum is the other half of it. Alongside passed and failed there is not-applicable — the criterion cannot apply here, there is no audio, no video, no timing — and inconclusive: looked at, could not decide. inconclusive never counts as a pass. Teams resist that field at first, because it feels like recording your own indecision. It is the opposite: it is the only honest way to distinguish "we examined this and it is genuinely ambiguous" from "nobody has opened that page", and those two states demand completely different work.

"We do not know" has no representation in the output format

Here is the part that decides whether the whole exercise is worth anything.

Internally, a claim can come back incomplete: WCAG's conformance requirement gives no partial credit, so a claim at a level means every criterion at that level is satisfied, and one criterion nobody has looked at makes the claim incomplete. Externally, the European model statement admits three values — fully compliant, partially compliant, non-compliant. There is no fourth for "the assessment is not finished."

The entire temptation of compliance reporting sits in that mismatch. Unknown looks close to partial. Rounding it down feels conservative, even responsible. It is neither: it publishes a claim about criteria nobody examined, in a document whose only value is that it is checkable.

import { assess, statement } from "a11ytrail";

const claim = assess(evidence, { level: "AA" });
claim.status; // "incomplete" — 1 of 55 criteria have no conclusive evidence

statement(claim, organisation, new Date());
// throws: the evidence does not support any compliance status yet:
// criteria remain unevaluated. Finish the assessment, or publish a
// statement that says the assessment is under way.

The generator refuses. Not a warning, not a nullable status field that every caller will coalesce to something publishable — a thrown error, because the caller's job at that point is to go and check the thing, and any softer signal gets handled once and then handled everywhere by copy-paste.

We apply the same rule in payment and verification work: a derived status that has a state the output format cannot express must fail loudly at the boundary rather than pick the nearest legal value. The nearest legal value is where audits die.

A gap is not a defect

The complement of that rule is just as important and gets skipped more often. A criterion that passes on the home page and was never checked on checkout is not a failure. Report it as one and you send an engineer to fix code that may be perfectly fine, while the real answer — nobody looked at that page — never reaches the person who could schedule the test.

So coverage gaps travel separately from failures, and so do two other qualifiers that a flat pass/fail column destroys. Evidence ages: every check carries its date, and a page audited before four redesigns supports nothing, so staleness surfaces in the claim's caveats and in the published statement rather than being assumed away. And a pass recorded by a tool alone is flagged — on a criterion no tool can settle, such as 1.1.1 Non-text Content, it is called out separately. That is not weak evidence. It is absent evidence wearing a green tick, and it is the single most common way a compliance dashboard becomes fiction.

The parts a record of tests cannot answer

Some of the statement does not follow from evidence at all. Whether an exemption is a disproportionate burden. What alternative a user is offered for content that fails. What a failing criterion actually means for the person sitting in front of it. The date the statement was last reviewed.

Those come back as pending and are marked as such in the rendered Markdown, rather than filled with something reasonable:

const published = statement(claim, organisation, new Date());

if (published.pending.length > 0) {
  // the decisions no record of tests can settle, listed rather than guessed
}

console.log(toMarkdown(published));

A plausible sentence in one of those slots is worse than an empty one, because it reads as answered. Nobody re-opens a paragraph that already sounds finished. This is the same reason our review gate rejects a comment that restates the code: it consumes the attention that a real question would have received.

What it costs to run

Less than the spreadsheet it replaces, in machine terms — no runtime dependencies, and Node 22.18 or newer runs the TypeScript sources directly. The real cost is behavioural: someone has to record the check at the moment it happens, with the scope and the build named, and accept that the generator will refuse to publish until the record is complete. That refusal is the product. Everything else is formatting.

The scope is deliberately bounded to WCAG 2.2 levels A and AA — 55 success criteria. Level AAA is absent on purpose: nobody claims it for a whole product, and offering the option would invite a claim nobody can keep. The library builds the European model statement out of your own evidence; whether that satisfies a particular national implementation is a question for someone qualified to answer it.

What generalises beyond accessibility is the ordering. Most teams write the claim and then look for evidence to support it. Invert that, make the record the input and the document a projection of it, and the interesting engineering turns out to be everything the generator declines to say.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.

Invoice numbers that cannot skip or repeat

Shipmind Labs — Wed, 09 Sep 2026 13:26:06 +0000

Two invoices carrying the same number, or a year whose numbering jumps from 0041 straight to 0043, are not cosmetic defects. Someone reading the books finds them years later, long after everyone has forgotten which release caused it. VAT rules decide what appears on the lines of an invoice. The number decides whether the document is defensible at all. It is also the part of a billing system that gets written carelessly most often, because allocating an integer looks like the easy half of the problem.

We have built invoicing and payment services long enough to have seen both failure modes in production systems we inherited. This is how we separate the two concerns, and why the numbering half ends up in the database rather than in the application. The code below is from euinvoice, our own package for EU invoice documents: https://github.com/shipmindlabs/euinvoice

Two problems that only look like one

VAT is a decision over facts. The regime follows from the seller country, the buyer country, and whether the buyer's VAT identifier has been validated. Nothing about it is stateful, so the same facts produce the same answer today and in five years:

from euinvoice import decide_vat_regime

decision = decide_vat_regime(seller, buyer)

print(decision.regime)        # VatRegime.DOMESTIC
print(decision.vat_category)  # VatCategory.STANDARD
print(decision.invoice_note)  # text for the invoice footer, or None
print(decision.explain())     # facts and legal basis, line by line

A decision carries the facts it was made from and the article it rests on, so the document can still be explained when the people who issued it have moved on. A VatCategory.REVERSE_CHARGE line shifts the tax to the buyer, carries a zero rate, requires the buyer's VAT identifier, and cannot be mixed with taxable lines on the same invoice. That is all rule evaluation. You can test it with no database in sight.

Numbering works the other way round. It is the one place in an invoicing system where two concurrent requests must not be allowed to reach the same answer, and where the correct behaviour is defined by what happened before, not by what is true now. If you treat the two as one module, with a create_invoice function that computes tax and grabs a number in the same breath, numbering becomes untestable and tax logic becomes slow to test.

Why MAX+1 and a native sequence are both wrong

The naive implementation reads the highest number issued so far and adds one. Under read-committed isolation, two transactions read the same maximum and issue the same number. This is not a rare interleaving, it is the ordinary result of two people clicking a button at the same time, and it survives in codebases for years because staging traffic never produces it.

The usual correction is a native database sequence, which will not hand out the same value twice. But a sequence is deliberately non-transactional: it advances outside your transaction so that concurrent writers do not block each other, and a rolled back transaction does not give the value back. That is the wrong trade for invoice numbers. You trade duplicates for gaps, and a gap is the thing an audit asks about. "The nightly job crashed after allocating 0042" is not an answer anyone wants to write down.

So the counter has to be an ordinary row, updated inside the same transaction that writes the invoice. In euinvoice the store is a port and the caller owns the transaction:

class PostgresCounterStore:
    def __init__(self, connection):
        self._connection = connection

    def next_count(self, key):
        with self._connection.cursor() as cursor:
            cursor.execute(
                "INSERT INTO invoice_counters (series, period, count) "
                "VALUES (%s, %s, 1) "
                "ON CONFLICT (series, period) DO UPDATE "
                "SET count = invoice_counters.count + 1 "
                "RETURNING count",
                (key.series, key.period),
            )
            return cursor.fetchone()[0]

One statement, no read-then-write. The row lock taken by the update is held until the transaction commits, which serializes concurrent issuers on that one key, and only that one key. If the surrounding transaction rolls back, the increment rolls back with it and the number goes back rather than sitting there as a hole. That property is the whole reason the store is a port instead of a connection the library opens for itself. The library cannot know where your transaction begins, and it should not be the thing that decides.

InMemoryCounterStore ships with the package for tests and single-process use. It is not a fallback for production, and we do not pretend otherwise.

The library does not trust its own store

An adapter is where the bug will be. Someone replaces the upsert with a read-then-write during a refactor, or a second service gets pointed at a table that was copied without its data, and the sequence quietly breaks in a way that produces valid-looking numbers. SequentialNumbering therefore checks every value the store returns against the one before it, and refuses anything that is not the next integer:

class FixedStore:
    """A store that hands out prepared values, however wrong."""

    def __init__(self, values) -> None:
        self._values = list(values)

    def next_count(self, key):
        return self._values.pop(0)


def test_a_skipped_counter_is_rejected():
    numbers = numbering(store=FixedStore([1, 3]))
    numbers.next_number(date(2026, 3, 1))
    with pytest.raises(NumberingError):
        numbers.next_number(date(2026, 3, 1))

Repeats, skips, a counter that starts at zero and a non-integer counter all raise NumberingError. This is a contract test that runs in production. It does not replace the store's guarantee, and no in-process check can, since the other writer may be in another process entirely. What it does is turn a broken adapter into a failure at the first bad number instead of a discovery at the next audit. We would rather refuse to issue an invoice than issue one that has to be voided by hand.

Periods are a key, not a scheduled job

The other common bug is a January rollover implemented as a task that resets the counter. It resets too early, too late, or twice, and it does so once a year, which is probably the worst possible cadence for finding out. There is no reset in euinvoice. The period is part of the counter's identity:

numbering = SequentialNumbering(
    NumberSeries("INV", Period.YEARLY), InMemoryCounterStore()
)

issued = numbering.next_number(date(2026, 3, 1))

print(issued.number)   # INV-2026-0001
print(issued.counter)  # 1
print(issued.key)      # CounterKey(series='INV', period='2026')

An issue date in 2027 resolves to a different CounterKey, and a key that has never been used starts at one. Nothing has to run at midnight. Period.MONTHLY and Period.QUARTERLY work the same way, and Period.CONTINUOUS produces a key with no period token at all, for series that must never restart. Series do not share a counter either: sales invoices under INV and credit notes under CN count independently against the same store, because they are separate sequences in the books, and modelling them as one is a change you cannot undo later.

Note what is not in the key: the VAT regime. A domestic invoice and a reverse-charge invoice come from the same sequence. The regime decides the lines, the note in the footer and the rate. It has no business deciding the number.

What it costs to run

One row per series per period, and a lock on it for the duration of the issuing transaction. That is real contention, and you cannot avoid it, since a gapless sequence is a serialization point by definition. The practical consequence is that the transaction which issues a number has to be short: allocate the number and write the invoice, then do PDF rendering, delivery and anything that talks to a third party afterwards, outside it. InvoiceDocument.from_invoice and render_html are pure functions over a finished invoice for exactly this reason.

The second consequence is a product decision rather than a technical one: drafts do not get numbers. A number is drawn when the document becomes an invoice, not when someone opens a form, because a draft abandoned after allocation is a gap that nobody can explain later.

Neither of those is expensive. Both are much cheaper than the alternative, which is a spreadsheet reconciling issued numbers against the ledger, maintained by someone in finance who has learned not to trust the system.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.

Courier dispatch: refusal cooldown instead of a penalty score

Shipmind Labs — Tue, 08 Sep 2026 13:22:01 +0000

Dispatch systems that let a courier decline a job usually record the refusal as a penalty: a reliability score goes down, and the next assignment round reads that score. It works until someone asks what the number means, when it recovers, and why next week's roster changed after a single decline on a Tuesday afternoon. We have built enough queue-and-dispatch systems — collections workflows in lending, real-time moderation tooling for compliance teams, role-specific courier and warehouse apps for a dark-store delivery marketplace — to think the penalty model is the expensive one, and not because of the arithmetic.

The constraint: two clocks in one system

A roster is planned ahead. Weekly patterns are unrolled over a horizon, holidays drop out, and the result is something a person looks at days before it happens. A refusal happens on the other clock entirely: a job is offered at 12:04, someone declines, and the next offer goes out seconds later.

A penalty score couples those two clocks. The number written at 12:04 is read by the planner that draws a roster for a span that has not started yet, so a decline in the middle of a shift silently edits an artifact people have already arranged their week around. Worse, the score has to come back. Recovery means decay, decay means a scheduled job, and now the fairness of your dispatch depends on whether a cron ran. The state is durable, cumulative, and nobody — least of all the courier — can say when it ends.

What we actually want is narrow: a refusal should lower a courier's priority for the next assignments, and then stop mattering, without anyone writing a row to undo it.

A cooldown carries its own end

Our shift-planner library models this directly. It is public at https://github.com/shipmindlabs/shift-planner and still pre-alpha — the API is not stable yet — but the shape of the refusal handling is the part we would keep.

A refusal produces a lock over a half-open interval, and the lock knows when it stops:

from datetime import datetime, timedelta, timezone

from shift_planner import Cooldown

noon = datetime(2026, 5, 4, 12, tzinfo=timezone.utc)
lock = Cooldown(timedelta(minutes=20)).lock("anna", noon)

lock.holds_at(noon + timedelta(minutes=5))   # True
lock.remaining(noon + timedelta(minutes=5))  # timedelta(minutes=15)
lock.holds_at(noon + timedelta(minutes=20))  # False

There is no unlock, and none is needed. CooldownLock stores since and until, and holding is a comparison against a moment you pass in. Expiry is not an event that has to be delivered; it is a fact about the clock that becomes true on its own. That single property is what removes the background job, the sweep, and the whole class of bugs where a courier stays penalised because a worker process was down.

The interval is half-open, [since, until), the same convention shifts use for [start, start + length). A cooldown that ends exactly when the next offer arrives does not hold, and a shift that ends exactly when the next one starts is not an overlap. Getting one convention wrong in a system like this produces off-by-one behaviour that only shows up at the boundary, which is precisely where dispatch spends its time.

Dispatch becomes a pure read of the clock

The dispatcher composes a roster with a board of locks. Recording a refusal returns a new dispatcher rather than mutating one, so a decision is always a function of the state you were handed and the moment you were given:

from datetime import datetime, timedelta, timezone

from shift_planner import Cooldown, CooldownBoard, Dispatcher, Job, Roster, Shift

noon = datetime(2026, 5, 4, 12, tzinfo=timezone.utc)
roster = Roster(
    [
        Shift("anna", "depot-north", noon, timedelta(hours=4), capacity=5),
        Shift("boris", "depot-north", noon, timedelta(hours=4), capacity=5),
    ]
)

dispatcher = Dispatcher(
    roster,
    cooldowns=CooldownBoard(cooldown=Cooldown(timedelta(minutes=20))),
)
job = Job(location="depot-north", at=noon)

dispatcher.assign(job).worker  # 'anna'

after_refusal = dispatcher.refuse("anna", noon)
after_refusal.assign(job).worker  # 'boris', anna is cooling down
after_refusal.cooldowns.remaining("anna", noon + timedelta(minutes=5))
# timedelta(minutes=15)

later = Job(location="depot-north", at=noon + timedelta(minutes=20))
after_refusal.assign(later).worker  # 'anna', the lock lifted on its own

Nothing between the third call and the last one touched the board. No job ran, no row was updated, no dispatcher intervened. The courier came back into rotation because twenty minutes passed.

This is also why the behaviour is testable without a scheduler and without freezing a global clock. Time is an argument — assign takes a job with an at, refuse takes the moment of the refusal, remaining takes the moment you are asking about. A test that wants to know what happens nineteen minutes in says nineteen minutes; it does not sleep, and it does not patch anything.

Eligibility and ordering are different questions

A cooldown answers who is a candidate. It does not answer who gets the job. Those stay separate, because conflating them is how ranking systems become unexplainable.

Candidates are couriers on duty at the job's own location. The ordering among them is a policy — LeastLoaded is the default, and anything with a sort_key(candidate) method can replace it:

from shift_planner import Dispatcher, EarliestStart

dispatcher.assign(job, taken={"anna": 3}).worker
# 'boris', anna is carrying more work

Dispatcher(roster, policy=EarliestStart()).assign(job, taken={"anna": 3}).worker
# 'anna', on duty since 11:00

When you want to change how work is spread, you change the policy and the load you pass in. The refusal handling stays where it is. In the penalty-score model, both of those live in one number, and every tuning conversation turns into an argument about whether a decline should be worth more or less than a busy hour.

The plan is drawn, not patched

The long clock stays clean. A Plan unrolls ShiftPattern objects over a Horizon, dropping holidays and stopping once a worker reaches their limit for the span:

from datetime import date, time, timedelta

from shift_planner import Horizon, Plan, ShiftPattern

plan = Plan(
    horizon=Horizon(date(2026, 5, 4), days=7),
    patterns=[
        ShiftPattern(
            "anna",
            "depot-north",
            time(8),
            timedelta(hours=8),
            weekdays={0, 1, 2, 3, 4},
            capacity=12,
        ),
    ],
)

roster = plan.applied_to(roster)
plan.applied_to(roster)  # same result, drawing again is a no-op

The roster a plan yields depends on the plan alone. applied_to replaces exactly what the plan speaks for — its own workers inside the horizon — and leaves everything else untouched, so redrawing after an edit is safe rather than something you do carefully at night. Refusals never enter this path. Nothing that happened at 12:04 can change what Thursday looks like, which is the property that makes a published roster worth publishing.

The roster itself refuses to hold a contradiction: two shifts of the same worker that share time raise OverlappingShiftError at construction, naming both. A redraw that would have double-booked someone fails where you can see it instead of producing a plan that dispatch quietly disagrees with later.

What it costs to run

Almost nothing, and the places it does cost are worth knowing.

The board holds at most one lock per worker, so its size is bounded by headcount rather than by refusal volume. Tuning is a constructor argument: changing the cooldown from twenty minutes to ten is a config change, not a migration and not a backfill of scores computed under the old rule.

The number that matters is the relationship between the cooldown duration and how quickly the same job is re-offered. If a job bounces back around the ring faster than the cooldown lasts, the cooldown is doing its job. If the cooldown is shorter than the re-offer interval, a courier who declined can be handed the same job again in the same round, which reads as the system ignoring them. Set the duration above the interval you actually re-offer at, and check that assumption when the offer loop changes.

The failure mode is honest and should be handled outside the library: if everyone at a location is cooling down, assign returns nothing. That is the correct answer to "who takes this job" when nobody is eligible, and it belongs to the caller to escalate — widen the location, page a coordinator, hold the job. A penalty score never returns nothing; it always produces a ranking, including a ranking of people you should not be assigning to.

One more operational note: every moment in the system must be timezone-aware. Shift and CooldownLock both reject naive datetimes at construction, because comparing naive and aware datetimes raises a TypeError deep inside an overlap check, at the least useful possible moment.

Close

The design decision is not "be nicer to couriers". It is that a refusal has a natural duration and a score does not. Modelling it as an interval that expires by the clock removes the decay job, removes the accumulating state, keeps the planning horizon independent of what happened this afternoon, and gives the courier an answer to the only question they were ever going to ask: how long. Twenty minutes.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.

A permission check should return a denial, not False

Shipmind Labs — Sun, 06 Sep 2026 13:20:21 +0000

Most Django backends answer authorization questions with a boolean, and everything the check knew gets thrown away on the way out. A courier's app shows a refund button that returns 403, support asks why, and nobody can answer without reading the view. More logging around the call site does not fix that. What fixes it is making the check return a value that names the actor, the action and the rule that refused, and then reusing that same declaration for queryset scoping, object ownership and the Django admin. We build this shape often enough in operations backends that we extracted it into a library of our own, role-scopes.

One False, four questions

A boolean check collapses four questions that fail for different reasons and want different handling:

Is this actor a thing we know about at all?
Is this action a thing we know about at all?
Is this actor granted this capability in general?
Is this row theirs?

Only the third one is what people mean when they say "permission check". The first two are usually a typo or a stale role string arriving from a token claim, a user column, or another service. The fourth is a completely different bug class, and it is the one that gets exploited.

So the rules are named and ordered, and the name travels with the answer:

class Rule(str, Enum):
    """Rule consulted by a check, listed in the order it is applied."""

    ACTOR_KNOWN = "actor.known"
    ACTION_KNOWN = "action.known"
    PERMISSION_GRANTED = "permission.granted"
    OBJECT_OWNED = "object.owned"

Unknown actors and unknown actions are denials too, tagged actor.known and action.known, rather than exceptions. We chose that deliberately: a role string that no longer exists should refuse the request, not turn into a 500 that pages someone. The stack trace tells you the same thing the denial does, but only one of the two is safe to return to a client.

The matrix is data, in one file

Permission logic rots because it gets restated. A view knows one version, a serializer knows another, the admin knows a third, and the mobile client hides buttons according to a fourth. So the matrix is declared once, as data, and every mechanism reads it:

class Actor(str, Enum):
    """Party acting on the system."""

    CUSTOMER = "customer"
    COURIER = "courier"
    WAREHOUSE = "warehouse"
    RECEIVING = "receiving"
    SUPPORT = "support"
    BACK_OFFICE = "back_office"


ACTOR_PERMISSIONS: Mapping[Actor, frozenset[Permission]] = MappingProxyType(
    {
        Actor.COURIER: frozenset(
            {
                Permission.ORDER_VIEW,
                Permission.SHIPMENT_VIEW,
                Permission.SHIPMENT_PICKUP,
                Permission.SHIPMENT_DELIVER,
            }
        ),
        # ...
        # Back-office runs the business and holds every capability.
        Actor.BACK_OFFICE: frozenset(Permission),
    }
)

Permissions are named <resource>.<action> (order.refund, shipment.deliver, inventory.adjust) because the resource half is later what queryset scoping keys on. The mapping is a MappingProxyType of frozensets for a boring reason: nothing at runtime should be able to grant itself a capability by mutating the matrix it was checked against.

Declaring it as data also makes the inverse question answerable, and the inverse question is the one audits actually ask. Not "may a courier refund an order" but "who can refund an order at all":

actors_with(Permission.ORDER_REFUND)

That is a one-liner against the same declaration, not a grep across views.

The denial is a value, not a message

A check returns a Decision. It is falsy when denied, and it carries the denial:

check(Actor.SUPPORT, Permission.ORDER_CANCEL).allowed
# True

decision = check("courier", "order.refund")

str(decision.denial)
# 'courier may not order.refund: courier is not granted order.refund [permission.granted]'

decision.denial.as_dict()
# {'actor': 'courier', 'action': 'order.refund',
#  'rule': 'permission.granted', 'reason': 'courier is not granted order.refund'}

The Denial is a frozen dataclass with four fields and two renderings: __str__ for a log line and as_dict() for a JSON body. This is the part that pays for itself. The line an engineer reads in the logs and the object the client's frontend received are the same four fields, so a support conversation stops being an archaeology exercise. And because rule is a stable enum value rather than prose, denials aggregate. A sudden concentration of permission.granted denials on one actor and one action usually means the matrix and the product's expectations have drifted apart, and it shows up as a count before it shows up as a complaint.

In a view, require() raises a PermissionDenied that subclasses Django's own, so the framework still turns it into a 403 on its own, while carrying the structured denial for handlers that want the body:

from role_scopes import PermissionDenied, require

try:
    require(request.user.role, Permission.INVENTORY_ADJUST)
except PermissionDenied as exc:
    return JsonResponse(exc.denial.as_dict(), status=403)

Nothing here requires an exception handler to know anything about permissions. It formats a value.

"Not allowed at all" and "not on this row" are different failures

A permission says what an actor may do. It says nothing about which objects are theirs. The mistake worth naming, because we have inherited it more than once: detail and action endpoints check the role and stop there (a courier may deliver shipments) without asking whether this shipment was assigned to that courier. The list endpoint is filtered correctly, so the bug stays invisible until someone walks the URL space.

The slice is declared next to the permission, keyed by the resource half, so a view narrows a queryset without restating the filter:

# request.user carries `courier_id`
scope_queryset(Shipment.objects.all(), "courier", Permission.SHIPMENT_VIEW, request.user)
# Shipment.objects.filter(courier_id=request.user.courier_id)

scope_for(Actor.WAREHOUSE, Permission.INVENTORY_ADJUST).label
# 'inventory.own_store'

And the object check asks both questions against that same declared slice, so the row a list view hides is the row a detail view refuses:

owns("courier", Permission.SHIPMENT_DELIVER, shipment, request.user)
# True only when shipment.courier_id == request.user.courier_id

decision = check_object("courier", "order.view", someone_elses_order, request.user)
str(decision.denial)
# 'courier may not order.view: this order is outside order.own_assignment [object.owned]'

The rule is object.owned, not permission.granted, and that distinction is why we keep the rule in the value. "You may not do this at all" is a UI bug or a stale client. "You may do this, but not on that row" is somebody probing identifiers. Those two lines should stay distinguishable in a log.

The same declarations split the admin

Internal tools are where role logic is most often re-derived, because Django's admin has its own permission vocabulary and mapping roles onto it by hand is tempting. We do not. The adapter in role_scopes.contrib.admin answers the admin's per-model questions from the same matrix and the same scopes the API uses, so back-office sees everything because BACK_OFFICE holds frozenset(Permission), and warehouse staff opening the same model see their own store's slice because that is what inventory.own_store already says.

The shape it produces is the shape you would otherwise repeat in every ModelAdmin:

from role_scopes import Permission, check, scope_queryset


class ShipmentAdmin(admin.ModelAdmin):
    def has_view_permission(self, request, obj=None):
        return check(request.user.role, Permission.SHIPMENT_VIEW).allowed

    def get_queryset(self, request):
        return scope_queryset(
            super().get_queryset(request),
            request.user.role,
            Permission.SHIPMENT_VIEW,
            request.user,
        )

In practice, granting a role a capability is one edit in one file, and the API, the DRF viewsets and the back-office screens agree afterwards without a second review pass. A REST Framework adapter exists for the same reason: an endpoint should stop hand-rolling the role checks its neighbours already spell out.

What it costs to run

Two things are worth knowing before adopting this shape.

It fails loudly on missing data. A principal that lacks the attribute a slice filters on raises MissingScopeKey, and an object missing the field the slice narrows on raises MissingObjectKey. Both could have been made to return an empty queryset instead, which is the tempting choice because it never pages anyone. It is also the choice where a misconfigured token silently widens or empties results, and nobody finds out for a quarter. We would rather have the 500.

The denial text is public API. order.own_assignment and permission.granted are internal labels, and returning them to a client means committing to them. We did that on purpose, since a client's engineer reading the reason is cheaper for everyone than a ticket, but it means a scope gets renamed carefully, and the reason line is never rewritten into something friendlier at one call site while the log keeps the old wording.

The underlying discipline is small: authorization is a question with more than two answers, so the code that asks it should be allowed to give more than two. Once the answer is a value, the log line, the error body and the internal tools stop being three separate implementations of the same rule.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.

The order lifecycle belongs in a table, not in your endpoints

Shipmind Labs — Sat, 05 Sep 2026 13:20:21 +0000

In most order systems, the rules that govern an order live nowhere in particular. The rule that the warehouse may ship only a paid order with stock on hand gets written in the ship endpoint, then again in the admin action, again in the batch job that clears yesterday's backlog, and once more in the frontend that decides whether to render the button. That is four implementations of one sentence, drifting apart quietly, and the drift is usually discovered by a customer sitting in a state nobody expected.

The same shape, over and over

We have built this object in several domains. A lending marketplace has moderation and issuance tiers, each with its own set of actors. A high-ticket asset marketplace moves a deal from listing through deposits and multi-party document signing to closing, with brokers and compliance both holding veto power at different moments. A dark-store delivery marketplace has role-specific apps for couriers, warehouse staff and store operations, which is another way of saying that the same order looks like a different set of available actions depending on who is holding the phone.

Underneath, they are the same shape. A small set of states, a set of triggers, a rule about who may fire which trigger and when, and paperwork about what actually happened. What differs is only the table of rows.

The if-chain version of this is not wrong on day one. One service, one endpoint, one if order.status != "paid": raise. It becomes wrong on the day a second caller appears, because the second caller is written by reading the first one, and reading code is a lossy way to copy a rule. It becomes expensive on the day someone from support asks a question that sounds trivial (can support cancel a paid order?) and the honest answer requires grepping views.

So we moved the rules into a data structure. The library we use for it is open: github.com/shipmindlabs/order-lifecycle. It is early development, and deliberately small, because the point is not the library. The point is that the lifecycle stops being control flow.

The lifecycle is a table of rows

A lifecycle is a table of (from-state, trigger, to-state) rows, not a pile of method calls:

from order_lifecycle import (
    COURIER,
    CUSTOMER,
    SUPPORT,
    State,
    Transition,
    TransitionTable,
    Trigger,
    WAREHOUSE,
)

NEW = State("new")
PAID = State("paid")
SHIPPED = State("shipped")
DELIVERED = State("delivered", terminal=True)
CANCELLED = State("cancelled", terminal=True)

PAY = Trigger("pay")
SHIP = Trigger("ship")
DELIVER = Trigger("deliver")
CANCEL = Trigger("cancel")

TABLE = TransitionTable(
    (
        Transition(NEW, PAID, PAY, roles=CUSTOMER),
        Transition(PAID, SHIPPED, SHIP, roles=WAREHOUSE),
        Transition(SHIPPED, DELIVERED, DELIVER, roles=COURIER),
        Transition(NEW, CANCELLED, CANCEL),
        Transition(PAID, CANCELLED, CANCEL, roles={CUSTOMER, SUPPORT}),
    )
)

str(TABLE.find(NEW, PAY))                 # 'new --pay--> paid [customer]'
TABLE.available(PAID, role=WAREHOUSE)     # -> (paid --ship--> shipped [warehouse],)

Every type is a frozen dataclass, so the table is hashable, comparable, and safe to share as a module-level constant. That matters more than it sounds. A lifecycle you can hold in a variable is a lifecycle you can pass to a test, diff between two versions, and print for a person who does not read Python.

Cancellation is not a special mechanism here, it is two more rows. A cancellation from NEW is open to anyone, and a cancellation from PAID names the customer and support explicitly. The interesting policy question, who is allowed to cancel after money has moved, is answered in one visible place instead of being implied by the absence of a check.

A broken table fails at import

The table validates itself when it is constructed, which in practice means at import time, which in practice means in CI. Two invariants are enforced. A terminal state may not be the source of any transition:

def __post_init__(self) -> None:
    if self.source.terminal:
        raise ValueError(
            f"state {self.source.name!r} is terminal; no transition may leave it"
        )

And a (source, trigger) pair may appear only once:

for row in rows:
    key = (row.source, row.trigger)
    if key in index:
        raise ValueError(
            f"duplicate transition for state {row.source.name!r} "
            f"and trigger {row.trigger.name!r}"
        )
    index[key] = row

The second one is the quiet win. In an if-chain, two branches that both match are a real possibility, and which one wins probably depends on the order they were added in over three years. Here the ambiguity cannot be constructed. find(state, trigger) returns exactly one row or None, and a lifecycle that contradicts itself breaks the build rather than a customer's order.

Wrong actor and wrong moment are different answers

Roles answer who. Conditions answer when, and they are named predicates over the order that carry the sentence they will use when they refuse:

from order_lifecycle import Condition, flag

PAYMENT_CONFIRMED = flag(
    "payment_confirmed",
    name="payment confirmed",
    requires="the payment must be confirmed",
)
IN_STOCK = Condition(
    "in stock",
    lambda order: order["units_available"] > 0,
    "every line item must be in stock",
)

ship = TABLE.find(PAID, SHIP)   # with conditions=(PAYMENT_CONFIRMED, IN_STOCK)
ready = {"payment_confirmed": True, "units_available": 3}

ship.allows(WAREHOUSE, ready)   # -> True
ship.allows(CUSTOMER, ready)    # -> False, wrong actor
ship.allows(WAREHOUSE, {"payment_confirmed": False, "units_available": 3})
# -> False, right actor, wrong moment

Keeping those two questions separate is what makes a refusal usable by an operator. "Not allowed" sends a support agent to an engineer. "You may ship this, but the payment is not confirmed yet" sends them to the payment page:

[str(result) for result in ship.unmet({"payment_confirmed": False, "units_available": 0})]
# -> ['payment confirmed: the payment must be confirmed',
#     'in stock: every line item must be in stock']

A guarded transition also refuses a caller that supplied no role at all, so ship.permits(None) is False. Anonymous internal callers do not get a free pass because someone forgot to thread the actor through.

The client stops re-deriving the rules

Once the table is data, the frontend does not need a second implementation of it. One endpoint asks the table what this actor may do to this order right now:

TABLE.available(PAID, role=WAREHOUSE, context=order)

Conditions are only evaluated when a context is supplied, so the same call serves both the cheap question (what does this role ever do here) and the expensive one (what can it do to this specific order). A courier app renders the buttons it is given, and when the policy changes, it changes in the table and the app follows without a release.

The permission matrix becomes a query rather than an archaeology project:

TABLE.roles              # every role the table guards a transition with
TABLE.for_role(SUPPORT)  # every transition support may fire, guarded or open

for row in TABLE:
    actors = ", ".join(sorted(role.name for role in row.roles)) or "anyone"
    print(f"{row.source.name:10} {row.trigger.name:10} {row.target.name:10} {actors}")

We generate that listing into the documentation for compliance and support review. It is the same object the code executes, so it cannot be out of date.

Applying a trigger, and what it leaves behind

Declaring the table is half of it. The machine applies a trigger against an order or refuses it with a reason, hooks declared on the row run around the transition, and every applied transition is appended to an immutable history of what changed, when, and by whom.

The history being produced by the machine, rather than logged by the caller, is the part we insist on. History written by call sites is history that is missing exactly where someone was in a hurry: the admin override, the backfill script, the incident fix. When the only way to change state is to apply a transition, and applying a transition appends a record, the audit trail cannot have holes of that kind. Hooks belong on the row for the same reason. A notification that must accompany a shipment is a property of the shipment transition, not of whichever endpoint happened to trigger it this time.

What it costs to run

The table is a module-level constant, and constants outlive orders. Orders that are in flight when the table changes were created under the previous rules, so removing a row is a migration question, not an edit. We add rows freely and remove them deliberately, after checking what is currently sitting in the affected states.

Conditions must be cheap, pure reads over a context that is already loaded. available() evaluates every condition on every candidate row, so put a network call in a predicate and you have built an N+1 into your order screen. Anything requiring a remote check gets resolved before the call and passed in as a field on the context.

The machine is not concurrency control. Two shipments racing on the same order is a database problem, and it stays one: the state write is a compare-and-set on the order row, committed in the same transaction as the history append. Hooks that touch the outside world run against a state that has already committed, because a notification about a shipment that got rolled back is worse than a late notification.

And the history only grows. That is the intended trade, we think: storage is cheap, and reconstructing what happened to an order from application logs is not.

The close

Nothing here is clever. The whole argument is that the rules of an order are a small, finite, boring data structure, and that the moment you express them as branches, you lose the ability to validate them, query them, print them, or guarantee they were followed. Every service, screen and script that touches the order then re-derives the same sentences slightly differently. Writing the table down once is not architecture, it is refusing to type the same rule four times.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.

Promo code rejections belong in the type system

Shipmind Labs — Thu, 03 Sep 2026 13:21:58 +0000

A promo code that fails at checkout has to serve two audiences at once: the buyer, who needs to know whether to fix something or give up, and the business, which needs to know which rule fired and how often. A boolean serves neither, and a human-readable message serves the buyer poorly and the business not at all. This is how we model promotion rules so that a refusal is a value with a type, and why the arithmetic behind the discount belongs inside the money type rather than in call-site checks.

The constraint that makes this harder than it looks is that the same refusal is consumed in at least three places with incompatible needs. The checkout UI wants a sentence the buyer can act on. The API contract wants a stable machine key that survives copy edits and translation. Analytics wants a closed set it can group by, because "how many carts lost a discount to the per-customer cap" is a campaign question, not a support question. A boolean collapses all three into one bit. A string satisfies the first and rots the other two: the day somebody rewords "This code has expired", the dashboard quietly splits into two buckets and the mobile client that matched on that string stops recognising the case.

What a boolean actually costs

The expensive part of is_valid() -> bool is not the missing sentence. It is that the caller now has to re-derive the reason, and to do that it has to re-implement the rules: compare the window itself, look at the usage counts itself, check the assignment list itself. The library knew exactly which rule stopped the redemption and threw that knowledge away one stack frame before the only place it was needed. Every caller then rebuilds an approximation, and the approximations drift — the web checkout and the mobile app disagree about whether a code is expired or exhausted, which is a support ticket nobody can reproduce.

We have hit this shape in payment and compliance work often enough to treat it as a design smell in its own right: validation that knows why but returns only whether. In our promotion engine the check returns the reason, and returns None to mean usable — the absence of an obstacle rather than a positive "yes":

from datetime import datetime, timedelta, timezone
from decimal import Decimal

from promocodes import (
    PercentageDiscount,
    PromoCode,
    UsageCounts,
    UsageLimits,
    ValidityWindow,
)

start = datetime(2026, 1, 1, tzinfo=timezone.utc)
welcome = PromoCode(
    "welcome10",
    PercentageDiscount(Decimal("10")),
    window=ValidityWindow(start, start + timedelta(days=30)),
    limits=UsageLimits(total=1000, per_customer=1),
)

now = start + timedelta(days=3)
welcome.check(customer="alice", usage=UsageCounts(total=12), now=now)
# None -> usable
welcome.check(customer="alice", usage=UsageCounts(12, for_customer=1), now=now)
# Rejection.CUSTOMER_LIMIT_REACHED

check() reports the first rule that stops the redemption. It does not accumulate a list, because a checkout screen shows one reason and a funnel chart attributes one cause; a list would only push the choice of which one matters back to the caller.

The reason set is part of the public API

A Rejection carries two faces. Rejection.slug is the machine-readable key that goes into the API envelope, the event stream and the group-by. Rejection.value is the human sentence, useful as a default and as documentation of what the key actually means:

rejection = shipping.check(total=Money(Decimal("12.00"), "EUR"))
{"error": rejection.slug, "detail": rejection.value}
# {'error': 'below_minimum',
#  'detail': 'the order total is below the minimum this code requires'}

Once those slugs are shipped they are a contract, in the same way response codes are. That is a feature: it forces the reason set to be designed rather than accreted.

slug	reported when
`not_started`	the validity window opens later
`expired`	the validity window has closed
`exhausted`	the global usage cap is reached
`customer_limit_reached`	this customer used the code as often as allowed
`not_assigned`	the code belongs to other customers
`customer_required`	the rules need a customer and none was given
`below_minimum`	the order total is under `minimum_total`
`total_required`	the code has a minimum and no total was given

Two of those look like they should be exceptions and are deliberately not. customer_required and total_required fire when the rules need an input the caller did not supply — an anonymous cart hitting a per-customer code, a code with a basket minimum evaluated without a basket. Answering "invalid" would be a lie to the buyer, and raising would make a routine integration state look like a crash. Making them ordinary members of the set pays off in the dashboard: a spike in below_minimum is a campaign design question, while a spike in total_required is our bug, and no amount of grepping a message string tells those two apart reliably.

Convenience derives from the reason, never the reverse

Around the typed answer sit the shapes callers actually want. is_usable() collapses the reason to a bool for the places that genuinely only need a gate. validate() and apply() raise PromoCodeRejected, which carries the same reason on its rejection attribute, for code paths where a failure should abort rather than branch. The direction matters: you can always throw information away at the edge, and you can never reconstruct it after the library has.

That is what lets an HTTP handler stay this small, with no rule knowledge in it at all:

from promocodes import PromoCodeRejected, redeem

try:
    receipt = redeem(code, store, order_total, customer=customer_id, now=now)
except PromoCodeRejected as exc:
    return {"error": exc.rejection.slug, "detail": exc.rejection.value}, 422

return {"discount": str(receipt.discount), "payable": str(receipt.total)}

The localisation layer belongs on the far side of that boundary, keyed by slug. The English sentence is a default, not an identity.

The other half of the bug is arithmetic

Typed reasons fix the question "may this code be used". They do nothing for the question "how much comes off", and that one has its own family of call-site mistakes: a fixed 80 EUR voucher against a 49.99 EUR basket, a percentage rounded in a currency that has no cents, a discount in one currency applied to a total in another. Each is usually patched with an if next to whichever caller hit it first, and the next caller writes a slightly different if.

We put the clamp in the discount type instead, so there is no call site that can skip it:

def compute(self, total: Money) -> Money:
    """Return the discount for ``total``, never negative and never larger."""
    if total.is_negative:
        raise ValueError(f"order total cannot be negative: {total}")
    raw = self._amount_for(total)
    if raw.currency != total.currency:
        raise ValueError(
            f"cannot apply a {raw.currency} discount to a {total.currency} total"
        )
    if raw.amount <= 0:
        return Money.zero(total.currency)
    if raw.amount >= total.amount:
        return Money(total.amount, total.currency)
    return raw

So an oversized voucher settles the basket and stops:

total = Money(Decimal("49.99"), "EUR")
FixedDiscount(Money(Decimal("80.00"), "EUR")).compute(total)  # 49.99 EUR

Note which failures raise and which do not. A negative order total and a currency mismatch raise, because they are impossible inputs — somebody upstream is broken and hiding it produces a wrong ledger entry hours later. An oversized discount clamps, because it is a perfectly normal business situation: the campaign was written for larger baskets. Rejections describe rule outcomes, exceptions describe states that should never reach the function, and keeping the two categories apart is most of what makes an engine like this pleasant to integrate.

Rounding gets the same treatment. PercentageDiscount multiplies the total by the percent and shifts by two digits, which keeps the product exact, so the only rounding is the explicit quantize afterwards — half-up by default, to the smallest unit the currency is actually settled in. minor_unit_exponent is what makes JPY come out in whole yen and the three-decimal currencies keep their third digit, instead of every caller assuming two.

The write path speaks the same vocabulary

check() only reads rules; spending a code is a write, and writes race. redeem() records a redemption only if the counters it was checked against are still the ones in storage; if they moved, the write is refused, the counts are re-read, the rules run again, and the caller either redeems against fresh counts or gets an ordinary PromoCodeRejected. Passing the payment provider's event id as idempotency_key makes a redelivered webhook free — the receipt comes back with replayed=True and no counter moves.

The part worth copying is that contention does not invent a second error vocabulary. A lost race resolves into either a receipt or one of the same eight reasons, so callers never grow a separate branch for "try again later", and the funnel chart does not sprout a bucket that means "our locking".

What it costs to run

A closed reason set is a versioned contract: adding a member is an API change, consumers that switch on slug need a default branch, and "just add a string here" is no longer available as a shortcut. Sentences in Rejection.value are English defaults and need a translation table keyed by slug the moment there is a second locale. The rounding mode is a policy decision that has to match whatever finance reconciles against, which is why it is an argument rather than a constant. And the clamp has an edge with a business meaning: a fixed discount silently truncates on a small basket, so a campaign that should refuse instead of truncating expresses that as minimum_total — a rejection, not a number.

The engine is small and public: https://github.com/shipmindlabs/promocodes. The rule it exists to demonstrate is one we apply well beyond promotions. When a component knows why it said no, that knowledge is the most valuable thing it produces, and it should leave the function as a value with a type — not as a bit, and not as prose.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.

Notification Fan-Out Needs a Stop Condition, Not a Retry Loop

Shipmind Labs — Mon, 31 Aug 2026 13:22:38 +0000

A service that turns one event into push, chat and email messages is easy to build and hard to keep honest. The failure that reaches support is almost never a dropped message; it is the second and third message, arriving after the user has already handled the thing they were being nagged about. We have built multi-channel notification layers more than once — fan-out to WhatsApp, Telegram, mobile push and web push — and the part that decides whether the system feels competent is not the sending. It is knowing when to stop.

The event is not the notification

An event happens: a payment needs confirmation, a document is waiting for a signature, a verification case has been returned to the customer. The naive service treats that as one message per channel, enqueued at once. Every channel then races the user, and at least one of them loses.

The model that survives production has three levels rather than one.

A notification is a decision that this recipient should be told this thing, once. It carries a dedup key, so that the same underlying state producing two events does not produce two ladders.

A delivery step is one attempt, on one channel, at one time. Steps are ordered.

A resolution is the fact that the notification no longer needs delivering. It is written by whoever observes the user acting: the API handler that accepts the confirmation, the endpoint that marks an in-app item as read, the webhook that reports a reply.

Only the first two belong to the notification service. The third is written from outside it, and that asymmetry is the whole design.

create table notification (
    id           bigserial primary key,
    recipient_id bigint      not null,
    kind         text        not null,
    dedup_key    text        not null,
    payload      jsonb       not null,
    created_at   timestamptz not null default now(),
    resolved_at  timestamptz,
    resolution   text,
    unique (recipient_id, dedup_key)
);

create table delivery_step (
    id              bigserial primary key,
    notification_id bigint      not null references notification (id),
    step_no         smallint    not null,
    channel         text        not null,
    send_after      timestamptz not null,
    state           text        not null default 'pending',
    attempts        smallint    not null default 0,
    provider_ref    text,
    unique (notification_id, step_no)
);

create index delivery_step_due
    on delivery_step (send_after)
    where state = 'pending';

Everything below is the machinery that keeps resolved_at authoritative.

The ladder is data, not code

Escalation is configuration, one ladder per notification kind, because the delays are a product decision and they change far more often than the dispatcher does.

@dataclass(frozen=True)
class Step:
    channel: str
    after: timedelta


LADDERS: dict[str, list[Step]] = {
    'payment_action_required': [
        Step('push', timedelta(0)),
        Step('chat', timedelta(minutes=10)),
        Step('email', timedelta(hours=2)),
    ],
    'document_awaiting_signature': [
        Step('push', timedelta(0)),
        Step('email', timedelta(hours=4)),
    ],
}


def schedule(conn, notification_id: int, kind: str, now: datetime) -> None:
    rows = [
        (notification_id, i, s.channel, quiet_hours_shift(now + s.after))
        for i, s in enumerate(LADDERS[kind])
    ]
    conn.executemany(
        'insert into delivery_step '
        '(notification_id, step_no, channel, send_after) '
        'values (%s, %s, %s, %s) on conflict do nothing',
        rows,
    )

Two details earn their place. All steps are written at scheduling time rather than lazily after the previous one completes, so the ladder is inspectable: when someone asks why a customer received three messages, the answer is a single row-set, not a reconstruction from logs. And quiet hours move a step forward instead of dropping it — a suppressed step is a message the user never gets, while a delayed step is one they get in the morning.

Cancellation happens at claim time

The obvious way to stop a ladder is a sweep: when the notification resolves, set its pending steps to cancelled. Do that, but do not depend on it. It is an optimisation, and it races with a dispatcher that has already picked the row up.

Correctness comes from re-checking the stop condition inside the same statement that claims the work.

with due as (
    select s.id
      from delivery_step s
      join notification n on n.id = s.notification_id
     where s.state = 'pending'
       and s.send_after <= now()
       and n.resolved_at is null
     order by s.send_after
     limit 50
       for no key update of s skip locked
)
update delivery_step s
   set state = 'sending',
       attempts = attempts + 1
  from due
 where s.id = due.id
returning s.id, s.notification_id, s.channel, s.attempts;

The join is the point. A step is never sent because it was due; it is sent because it was due and the notification was still open at the instant of claiming. With that in place the cancellation sweep can be late, can be lost, can run in another transaction entirely, and the worst outcome is a row that sits in pending until a dispatcher discards it.

One race remains and it cannot be closed: the user acts while the provider call is already in flight. That window is the duration of one HTTP request rather than the ten minutes between ladder steps, and it is the right place to stop engineering. Write it down in the runbook and move on.

The adapter contract, and the key that must not change

Every channel is an adapter with the same three outcomes: the provider accepted it, the provider permanently refused it, or the call failed in a way worth retrying.

def dispatch(conn, step, notification, adapter) -> None:
    key = f'{notification.id}:{step.step_no}'
    result = adapter.send(
        recipient_id=notification.recipient_id,
        payload=notification.payload,
        idempotency_key=key,
    )
    match result:
        case Sent(provider_ref):
            mark(conn, step, 'sent', provider_ref=provider_ref)
        case Rejected(reason):
            mark(conn, step, 'rejected')
            disable_contact(conn, notification.recipient_id, step.channel, reason)
            promote_next_step(conn, notification.id, step.step_no)
        case Failed():
            mark(conn, step, 'pending', send_after=backoff(step.attempts))

The idempotency key is built from the notification id and the step number, and deliberately not from the attempt counter. A retry after a timeout must present the same key as the call that timed out, because the ordinary explanation for a timeout is a provider that accepted the message and failed to say so. Put the attempt number in the key and every ambiguous timeout becomes a duplicate on someone's phone.

The Rejected branch is the one that gets skipped. A revoked push token, a chat account that blocked the sender, an address that hard-bounced — these are permanent facts about the contact, not transient send failures. Retrying them burns quota, and worse, it leaves the ladder waiting on a channel that will never work. So the branch does two things at once: it marks the contact dead so no future ladder schedules it, and it pulls the next step forward instead of leaving the user in silence for two hours because step one was addressed to a phone that no longer exists.

What it costs to run

The partial index on pending steps keeps the poll to one small index scan per tick regardless of table size, and the table does grow — delivery_step is where the volume lives, so it needs a retention job from day one, not after the first slow query.

Three signals are worth a dashboard.

Due lag: now() minus the send_after of the oldest pending due step. Non-zero and rising means the dispatcher is behind. For a payment ladder that is a product outage even though nothing has thrown an error.

Escalation depth: the distribution of the step number at which notifications resolve. This is the most useful number the service produces and it is not an infrastructure metric. If a kind of notification routinely resolves at step three, either channel one is not arriving or the text in it does not tell people what to do.

Cancellation ratio: the share of steps cancelled by the sweep or discarded at claim time. It should be substantial. A ladder that almost never cancels is a ladder whose stop condition is not being written — somebody shipped a new action path and forgot to resolve the notification, and the system is now sending messages nobody needs.

Close

The fan-out is the easy half; anything can put a message on three queues. What makes a notification service feel like it was built by people who have watched real users is that it treats delivery as a sequence whose stop condition is owned elsewhere, re-reads that condition at the last possible moment, and records a dead contact as a fact rather than an error. The rest is adapters.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.

An audit trail is a typed changeset, not a log line

Shipmind Labs — Sun, 30 Aug 2026 13:29:30 +0000

Most Django projects discover their audit requirement late. A compliance reviewer asks who moved an application to the next issuance tier and when, and the answer has to be assembled from application logs, a request id, and somebody's recollection of which deploy was live that week. That is forensics, not audit. An audit trail is a data structure the application produces at write time: a typed, field-level changeset with an actor already resolved and attached. Everything reconstructed afterwards is an inference with a convincing timestamp on it.

We kept rebuilding the same thing across compliance tooling, moderation panels and payment back offices, so we extracted it into a small library we maintain in the open: model-audit. It is pre-alpha and the public API is not stable yet, but the two decisions underneath it are the ones we would argue for in any codebase, with or without this package.

The failure mode: objects that were flattened into strings

The usual first implementation is a log call in save() or in a signal handler: the model label, the primary key, the user, and an f-string of what changed. It survives contact with a code review because it is honest about being a log line. It fails later, when someone needs to answer a question rather than read a story.

Three things are lost in that flattening. The values were stringified, so "10" and 10 and Decimal("10.00") are now the same character sequence. The field list is whatever the author remembered to interpolate, which drifts the moment a field is added. And the actor is whatever happened to be in scope at that point in the call stack — often a request in a view, and nothing at all in a management command or a queue worker.

Once the record is a string, questions like "which invoices had total changed by a service rather than by a user" become a parsing exercise against log storage. The information was present at the moment of the write and was thrown away in the act of recording it.

A changeset is a value, and it should behave like one

The alternative is to make the comparison produce a typed object. diff() takes two mappings of field values and returns a Changeset of frozen FieldChange dataclasses:

from model_audit import diff

stored = {"title": "Draft", "views": 10, "published": False}
incoming = {"title": "Release notes", "views": 10, "published": True}

changeset = diff(stored, incoming, exclude=["views"])

bool(changeset)   # True
changeset.fields  # ('title', 'published')
changeset.as_dict()  # {'title': ('Draft', 'Release notes'), 'published': (False, True)}

The changeset is ordered, iterable, indexable by field name, and truthy only when something actually differs. That last property is worth more than it looks: "an update that changed nothing produces no audit record" stops being a special case a caller has to remember and becomes a property of the value itself.

Two details in the comparison matter more than the container does.

The first is absence. A field present on only one side is reported with a MISSING marker on the other, exposed as is_addition and is_removal on the change. A field that was never set is a different state from a field explicitly set to None, and that distinction dies the moment you render either one into text. In an audit trail for a document workflow or a KYC review, "this attribute appeared" and "this attribute was cleared" are genuinely different events.

The second is equality. Python will happily tell you that True == 1, which means a naive comparison silently misses a column that changed from an integer flag to a boolean one:

from model_audit import diff

diff({"verified": 1}, {"verified": True}).fields  # ('verified',)

The diff treats a bool replacing a number as a real change. This is the kind of rule that is easy to state, easy to get wrong once, and impossible to notice afterwards — because the evidence that it was wrong is precisely the record that was never written.

The core has no framework in it

The module that does the comparison imports dataclasses, typing and collections.abc. It does not import Django. The framework layer sits on top and does one job: feed the core two mappings of model state.

That separation is not architectural tidiness, it is what makes the guarantee testable. The claim an audit system makes is "we detect field-level change correctly and completely." If that claim can only be exercised through the ORM, every test of it also tests settings loading, database setup, signal wiring and save semantics, and the failures blur together. With a framework-free core, the claim is checked in isolation:

from model_audit import MISSING, diff


def test_field_present_on_one_side_is_an_addition():
    changeset = diff({"status": "draft"}, {"status": "draft", "reviewer_id": 7})

    assert changeset.fields == ("reviewer_id",)
    change = changeset["reviewer_id"]
    assert change.is_addition
    assert change.old is MISSING
    assert change.new == 7

No database, no settings module, no fixtures. The second payoff is reuse: the same core compares an incoming API payload against stored state, or two versions of a configuration document, or records from a store that is not an ORM at all. We have written that comparison by hand in several systems that had nothing in common except needing to know what changed.

Who: resolved at the write, not inferred later

The other half of an audit row is attribution, and it is where most implementations quietly reach for a global. A thread-local holding the current request is convenient and works until the change happens in a Celery task, a management command, or a webhook handler — at which point the audit row either says nothing or, worse, says whatever the last request left behind.

We made resolution explicit and total. The call site passes whatever it already has, and the resolver normalises it:

from model_audit import SYSTEM, Actor, resolve_actor

resolve_actor(request)           # Actor(kind=USER, id='42', label='ada')
resolve_actor(request.user)      # same
resolve_actor("billing-worker")  # Actor(kind=SERVICE, id='billing-worker', ...)
resolve_actor(None)              # UNKNOWN
resolve_actor(None, fallback=SYSTEM)

Actor.user(42, "ada").as_dict()  # {'kind': 'user', 'id': '42', 'label': 'ada'}

An unauthenticated user resolves to ANONYMOUS, an absent one to UNKNOWN. Neither is an error. An audit layer that raises inside a save turns a missing attribution into an outage, and the first production incident of that kind ends with the audit layer being disabled. Recording the gap honestly is better than refusing the write, and actor.is_known lets a reader separate an attributed change from an unattributed one instead of guessing.

Signals are the case where nothing can be threaded through, so there is an opt-in ambient actor bound for the duration of a block:

from model_audit import actor_context, current_actor, resolve_actor

with actor_context(request):
    current_actor()                    # the request's actor
    resolve_actor(None, ambient=True)  # same, via the resolver

current_actor()                        # UNKNOWN again

The trade-off is deliberate and documented rather than hidden. The binding is context-local, so it follows await inside a task but is not inherited by threads or executor workers started within the block, and it makes the actor invisible at the call site. That is why resolve_actor() never reads it unless asked with ambient=True: the convenient path stays available, but you have to name it.

Recording on save, and what it costs to run

Recording is opt-in per model. register() connects post_init and post_save for that model and leaves every other model untouched.

from model_audit import register, subscribe

register(Invoice, exclude=["search_vector"])


@subscribe
def write_to_log(record):
    print(record.action, record.model, record.pk, record.changes.as_dict())


invoice.total = 120
invoice.save()
# updated app.Invoice 7 {'total': (100, 120)}

A record carries the model label, the primary key, the Action, the actor, the changeset and a timestamp, and as_dict() flattens it for whatever store you keep it in. Because signals carry no call-site actor, the recorder reads the ambient one — wrapping the request or the job in actor_context() is what turns UNKNOWN into a name.

The running cost is one extra snapshot of the audited fields per loaded instance and one comparison per save on registered models. The field selection is where that stays cheap: exclude drops single fields and fields narrows to an allow-list, a foreign key can be named either way, deferred fields are skipped, and relations are read by their stored id so snapshotting never issues an extra query. Timestamps that every save touches are dropped by default through NOISY_FIELDS, because an audit trail in which every row reports updated_at teaches readers to skim.

An audit row is not a second copy of the table

The last constraint is one we learned from systems where the audit store outlives and out-reads the data it watches. Retention on an audit table is usually longer, and the set of people who can read it is usually wider, than for the records it describes. So values of fields whose names read like a secret, a phone number or an identity document are replaced by REDACTED before the record reaches any receiver. The trail still proves that the field changed, and by whom, without becoming the easiest place in the system to harvest what changed.

That is the whole argument. An audit trail should be produced, not reconstructed; typed, not stringified; attributed at the write, not inferred from a log; and the part that decides what counts as a change should be small enough and plain enough to test without a framework in the room.

Originally published on shipmindlabs.com — where we write about payment systems, infrastructure and marketplace backends.