DEV Community: Shipmind Labs

A promo usage limit needs compare-and-set, not a read then a write

Shipmind Labs — Fri, 09 Oct 2026 13:24:04 +0000

A promotion capped at one use per customer and a thousand overall is two counters, and the obvious way to enforce them is a read, a check against the limits, and a write of the incremented values. Now picture two payment confirmations for the same code arriving at the same moment. Both read the same number, both pass the check, both write. The thousand-and-first redemption exists, and the customer who was allowed one has two. The whole defect lives in the window between the read and the write, and no amount of validation inside that window closes it.

We have built payment services, hosted checkout pages and marketplace flows for most of a decade, and promotion logic is where money bugs are cheapest to introduce and most awkward to explain afterwards. A discount larger than the basket is at least visible in a single order. An over-redeemed cap stays invisible until finance counts. Our promotion engine, promocodes, treats the counter as the hard part rather than the arithmetic, and this is the mechanism it settled on.

The read is a fact about the past

Here is the shape that loses. It uses our real types, and the package deliberately does not let you write it:

usage = store.usage_for(code.code, customer=customer)   # UsageCounts(999, 0)
if code.check(customer=customer, usage=usage, total=total) is None:
    store.increment(code.code, customer=customer)       # no such method, on purpose

usage_for answers a question about the past. By the time check has agreed that UsageCounts(999, 0) sits under a UsageLimits(total=1000, per_customer=1) cap, the number may already be 1000. The second webhook is not racing the first one's decision, it is racing its own read, and it wins, because an unconditional increment has no way to know what it was authorised against.

That is why the RedemptionStore protocol has no increment on it. The only write the store exposes already carries what it believed when you called it.

The write carries the counts it was validated against

def record(
    self,
    code: str,
    *,
    customer: Optional[str] = None,
    expected: UsageCounts,
    idempotency_key: Optional[str] = None,
) -> Optional[Reservation]:

expected is the counts the caller validated. The store increments only when the counts it finds are still exactly those, and returns None otherwise. In the reference implementation the whole check is one comparison:

current = self._counts(key, who)
if current != expected:
    return None
self._totals[key] = current.total + 1

Two details are worth pulling out. First, UsageCounts is compared as a value, so the global total and the per-customer count are one condition instead of two. A redemption by a completely different customer moves the global total and therefore invalidates your pending write, which is conservative and correct, because the global cap is the rule that was checked against that number. Second, None is not an error. It is the store saying nothing happened, which is the only honest thing it can say, since it has no idea whether the code is still usable at the new counts. Deciding that is the caller's job.

In the tests, that refusal shows up on its own, with no concurrency at all:

first = store.record("SAVE10", customer="alice", expected=UsageCounts(0, 0))
stale = store.record("SAVE10", customer="alice", expected=UsageCounts(0, 0))

assert first.usage == UsageCounts(1, 1)
assert stale is None
assert store.usage_for("SAVE10", customer="alice") == UsageCounts(1, 1)

A second write against counts that have already been spent is exactly what the losing webhook performs. Here it costs you a two-line test instead of a production incident.

On conflict the rules run again, not just the write

The tempting retry is to re-read the counts and write again. That is wrong in a way you only see at the boundary: the reason the counts moved may be the reason the code is now unusable. So redeem retries the whole decision rather than the increment.

for _ in range(attempts):
    usage = store.usage_for(code.code, customer=customer)
    code.validate(customer=customer, usage=usage, total=total, now=moment)
    reservation = store.record(
        code.code,
        customer=customer,
        expected=usage,
        ...
    )

Every pass re-reads usage_for and re-runs validate. If the redemption that beat us to it was the last one the cap allowed, the next pass does not reach the write at all: validate raises PromoCodeRejected with Rejection.EXHAUSTED, and the loser of the race is told it lost for the right reason. If there is still room, the loop writes against the fresh counts and succeeds. Contention inside the budget simply does not reach the caller:

def test_contention_within_the_budget_still_redeems():
    promo = PromoCode("CAP5", TEN, limits=UsageLimits(total=5))
    store = FlakyStore(InMemoryRedemptionStore(), refusals=2)

    receipt = redeem(promo, store, eur("80.00"), now=START, attempts=3)

    assert receipt.usage == UsageCounts(1, 0)
    assert store.inner.usage_for("CAP5") == UsageCounts(1, 0)

FlakyStore is four lines of delegation that refuse the first n writes and then behave, which is enough to test a compare-and-set loop deterministically without threads. We reach for that shape constantly, because concurrency bugs become testable the moment you can inject the refusal instead of trying to provoke it.

The budget is finite (DEFAULT_ATTEMPTS is 3), and when it runs out redeem raises RedemptionConflict, which is a RuntimeError and explicitly not a rejection. That distinction is the operational point of the whole design. A rejection is an answer for the buyer: the code expired, the cap is gone, this basket is too small. A conflict is an answer for us: the code is so contended that three honest attempts could not land a write. There is nothing to tell a buyer there, and nothing a buyer could do about it. A webhook handler should let that bubble up so the provider redelivers, and a sustained conflict rate on one code says something about that promotion rather than about that customer. Collapsing the two into one "could not redeem" response is how a hot code turns into a wave of support tickets about codes that were valid the whole time.

A repeated key returns the earlier reservation

Retried webhooks are not an edge case, they are the normal operating mode of every payment provider worth integrating. So the third outcome is a replay. When record gets an idempotency_key it has already seen, it returns the counts stored for that key with replayed=True and increments nothing:

first = capture(promo, store, cart, now=START, idempotency_key="evt_1")
again = capture(promo, store, cart, now=START, idempotency_key="evt_1")

assert first.replayed is False
assert again.replayed is True
assert again.usage == first.usage
assert store.usage_for("SAVE10") == UsageCounts(1, 0)

Notice what the replay returns: the earlier reservation, not a fresh success and not an error. The caller gets the same usage it got the first time, so an idempotent handler can render the same receipt twice, and the replayed flag is there for anyone who needs to know the difference (logs, reconciliation, a counter on redelivery rates).

The key only works if you enforce it where the increment is enforced. InMemoryRedemptionStore holds its _totals, _per_customer and _keys dictionaries under a single threading.Lock, which honours the protocol across threads in one process and nothing more; the class docstring says so rather than letting anyone find out in staging. For a real store the protocol's requirement is specific: back the key with a unique constraint written in the same transaction as the increment. A key checked in application code before the transaction is just another read-then-write race, with a longer window.

The counters move while the buyer is paying

The race between two webhooks has a slower sibling, the race between the checkout page and the payment confirmation. A basket priced at 10% off can sit in a payment intent for minutes while somebody else takes the last redemption, or the window closes, or the basket shrinks below the code's minimum.

So pricing and spending are separate calls. quote validates and prices without touching the counters. capture re-runs every rule through redeem against the clock and the counters of the moment the money actually moves, optionally against a changed total, and refuses with CaptureRejected, a PromoCodeRejected that carries the stale Quote, so a checkout API can tell the buyer that the code expired while they were paying. On refusal it records nothing:

with pytest.raises(CaptureRejected) as refused:
    capture(promo, store, cart, now=START)

assert refused.value.rejection is Rejection.EXHAUSTED
assert store.usage_for("LASTONE") == UsageCounts(1, 0)

The counter is still 1. Losing the second check costs the promotion nothing, and that property is what makes it safe to run the check at all.

What it costs to run

One extra read per attempt, and a write that can come back empty. In the uncontended case, which is almost every case, that is one read and one conditional write, no locks held across a network call, and no transaction kept open while a rule is evaluated. Under contention the cost is bounded by attempts, and the conflict test asserts that bound directly: store.writes == attempts. Nothing retries forever.

What it asks of the surrounding system is modest and not negotiable. The store's conditional write and its key uniqueness must sit in the same transaction as the increment. The idempotency key must be a fact the provider gives you and you persist, not something derived at handling time. And the three outcomes have to stay three: a receipt, a rejection the buyer can act on, and a conflict that belongs in your alerting. A cap enforced this way is a property of the write rather than a hope about timing, and that is probably the only version of it that survives two webhooks arriving together.

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

A blocked tag left on the page is one line of code away from running

Shipmind Labs — Thu, 08 Oct 2026 13:24:03 +0000

The usual way to hold a third-party script until the visitor consents is to leave it in the markup with type="text/plain" and swap the type back on accept. Nothing has executed, no request has gone out, and the DOM reads as compliant. It is also one assignment away from running, from any code on the page, at any time, with no decision involved. We build consent-gated tags as a registry instead: held until there is an answer, released only for the purposes that answer granted, and on withdrawal taken off the page and cleaned up after.

What parking actually guarantees

A script element with a type the browser does not recognise is inert. That part is true, and it is the whole appeal: paste the vendor's snippet exactly where the vendor said to paste it, add one attribute, ship.

What it does not give you is the property the notice claims. "Inert right now" and "cannot run unless the visitor allows it" are different guarantees, and the gap between them is a single line:

document.querySelector('script[type="text/plain"]').type = "text/javascript";

That line does not have to be malicious or even deliberate. It can be a consent library's own revive routine firing against a stale state, a tag manager container reactivating scripts it did not block, a "re-run third-party scripts after a route change" helper in a single-page app, or the next snippet someone pastes into the head. The refused vendor's code is sitting in the document of a visitor who refused it, and every one of those paths reaches it.

The visitor was told the vendor would not run. What was built is that the vendor is loaded but not started. Keeping the artefact one unrelated line away from execution is the loophole, and that nobody has flipped it yet is not a defence.

A tag is not queued work

In consentcore we separate the two, because they fail in different directions.

Queued work is a one-shot side effect: it runs once and it is over.

const gate = new Gate(state);

gate.when("necessary",  "session",   () => startSession());
gate.when("statistics", "analytics", () => loadAnalytics());
gate.when("marketing",  "pixel",     () => loadPixel());

// later, when the visitor decides
gate.update(accept(["statistics"], options));

Necessary work runs immediately and synchronously, so callers can rely on ordering. Nothing runs twice however many decisions arrive. Work whose category is withdrawn gets dropped rather than kept waiting, because holding a withdrawn callback in case the visitor changes their mind is the same loophole as the parked script, hidden in a closure instead of in the DOM.

A tag is not that shape. It keeps running after it starts, and consent can move under it: someone who accepted statistics can withdraw while the vendor's script is live on the page. A queue has nothing useful to say about that moment, because by then its job finished long ago. So tags are a registry. A tag stays registered whatever the current answer is, and what changes is whether it is on the page.

Hold, release, remove

export type Tag = {
  readonly id: string;
  readonly purpose: Category;
  readonly src?: string;
  /** For vendors that hand over a block of code rather than a URL. */
  readonly inline?: string;
  readonly attributes?: Readonly<Record<string, string>>;
  readonly cleanup?: () => void;
};

const tags = new Tags(state);

tags.register({ id: "analytics", purpose: "statistics", src: "https://cdn.example/a.js" });
tags.register({
  id: "pixel",
  purpose: "marketing",
  src: "https://cdn.example/p.js",
  cleanup: () => { document.cookie = "_pxl=; Max-Age=0"; },
});

tags.update(accept(["statistics"], options));  // analytics goes on the page, the pixel does not
tags.update(withdraw(options, state));         // the analytics element is taken off it

update takes a decision rather than a list of categories, so acceptance, a narrower custom answer and a withdrawal are all the same call. A later grant releases a removed tag again, which is a new answer to the same question, not a replay of the old one.

Ids are unique and a second registration under the same id throws DuplicateTag. The id is not decoration: it is how the element is found again when the answer changes.

Mounting behind a seam

Releasing and revoking are expressed against a two-method interface, and the DOM implementation is one of its implementations rather than an assumption baked into the registry.

export type TagHost = {
  mount(tag: Tag): void;
  unmount(tag: Tag): void;
};

export function domHost(where: { document?: TagDocument; root?: TagRoot } = {}): TagHost {
  // Looked up per call, not once: a module imported during server rendering
  // has no document, and the same host has to work after hydration.
  const owner = () =>
    where.document ?? (globalThis.document as unknown as TagDocument | undefined);

  return {
    mount(tag) {
      const document = owner();
      const root = where.root ?? document?.head;
      if (!document || !root) return;

      const element = document.createElement("script");
      element.setAttribute(TAG_ATTRIBUTE, tag.id);
      element.setAttribute(PURPOSE_ATTRIBUTE, tag.purpose);
      for (const [name, value] of Object.entries(tag.attributes ?? {})) {
        element.setAttribute(name, value);
      }
      if (tag.src) element.setAttribute("src", tag.src);
      if (tag.inline !== undefined) element.textContent = tag.inline;
      root.append(element);
    },

    unmount(tag) {
      const root = where.root ?? owner()?.head;
      if (!root) return;
      // Matched by reading the attribute rather than by building a selector:
      // the id comes from a caller, and a selector would have to escape it.
      for (const element of Array.from(root.querySelectorAll(`[${TAG_ATTRIBUTE}]`))) {
        if (element.getAttribute(TAG_ATTRIBUTE) === tag.id) element.remove();
      }
    },
  };
}

Three details earn their place here. The document is resolved per call rather than captured at import, because a module loaded during server rendering has none and the same host must keep working after hydration, so with no document, mounting and unmounting are no-ops rather than a crash and server rendering stops being a special case the caller has to remember. Removal matches by reading data-consent-tag off each element instead of composing a selector, because the id is caller-supplied and a selector would have to escape it. And TagElement, TagRoot and TagDocument are named narrowly enough that a test, or a renderer that is not a browser, can stand in without a fake window.

Every mounted element carries data-consent-tag and data-consent-purpose. That makes the page inspectable: open devtools and you can see what is running and under which answer. It is a different kind of evidence from the consent log, where the log says what the visitor chose and the attributes say what the page did about it.

Removing the element is not undoing the tag

Taking a script off the page stops nothing that already started. The cookie it wrote, the interval it set and whatever it hung on window all outlive the element. cleanup is where those are dealt with, and a registry without it is a registry that produces a tidy DOM and an untouched tracking cookie.

Cleanup is only as complete as what you know the vendor does, which is exactly the kind of knowledge that usually lives in prose. Declaring it as data is the cheaper option:

{ id: "acme-analytics", name: "Acme Analytics", purposes: ["audience"],
  policy: "https://acme.example/privacy", cookies: ["_acme"], transfers: "US" },

The cookie names in a vendor declaration and the cookie names in a cleanup function are the same fact written twice. Keeping both in one repository, diffed in the same review, is how you find out they have stopped agreeing.

The record has to run both ways

export type TagEvent = {
  readonly id: string;
  readonly purpose: Category;
  readonly action: "released" | "revoked";
  readonly at: string;
};

tags.history records releases and revocations alike. After a withdrawal the question is rarely "is it off the page now". It is "when did it come off, and was it ever on". A history of releases only cannot answer the second half, and the second half is the one that gets asked.

What it costs to run

Every third-party tag has to be named, filed under a purpose and given a cleanup. Prose in the cookie policy becomes code, which is uncomfortable for the tag nobody can explain, and that discomfort is probably doing useful work.

Re-release re-executes. Removing a script element and appending a fresh one on a later grant means the vendor's code runs from the top again. That is correct under this model, but a vendor that assumes it initialises once per page load needs checking before you lean on it.

Answers expire. The storage layer treats a decision as good for thirteen months (CONSENT_MONTHS), after which the notice is due again and tags are held until it is answered. A page that quietly assumed a one-time accept behaves differently in the visitor's second year.

Inline tags stay awkward. The inline field exists for vendors who hand over a block of code rather than a URL, which means that code sits in your bundle instead of behind a src you can read in the network tab.

Close

Parking a refused vendor as text/plain is a reasonable instinct, since keeping it nearby is what makes the accept path cheap. The cost is that the refusal path is not a refusal, only a pause that any line of code can end. A registry costs an id, a purpose and a cleanup per tag. What it buys is that "refused" means the vendor's code is not in the document, and "withdrawn" means it stopped being there at a time you can name.

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

A money input that regroups on every keystroke eats a digit

Shipmind Labs — Wed, 07 Oct 2026 13:24:03 +0000

A money field that reformats its own text while someone is still typing will swallow a character sooner or later. The user adds a digit, the field rewrites the string to move a group separator, the browser leaves the caret at the end of the new value, and the next keystroke lands somewhere other than where the person was looking. The formatter is almost never where the bug lives. The timing is: the text got rewritten while the value was still moving.

We build and operate money paths (payment services, hosted payment pages under a merchant's own branding, ledgering and reconciliation), and this is the most common defect we find in an otherwise careful checkout or payout form. A better regular expression will not fix it. What fixes it is a rule about when the field is allowed to touch the text at all, plus a policy for the two moments when a rewrite really is unavoidable.

Where the character goes

Here is the implementation almost everyone writes first, a controlled input that reformats on every change event.

function NaivePrice() {
  const [text, setText] = useState("");
  return (
    <input
      value={text}
      onChange={(event) => {
        const digits = event.target.value.replace(/[^\d.]/g, "");
        setText(new Intl.NumberFormat("en-US").format(Number(digits)));
      }}
    />
  );
}

The float is the famous problem with this code, and the least interesting one here. The other two are what the user actually feels.

The decimal point cannot be typed. 12. goes through Number and comes back as 12, formats as 12, and the dot disappears between the keypress and the render. The person presses it again and gets the same nothing. Nobody files this as a caret bug, but it is the same bug: the text got rewritten before it was finished.

The caret goes to the end. Writing a new string into the element's value discards the selection the browser had just maintained, and nothing in the handler puts it back. Editing in the middle of a number becomes impossible, because the next character appends at the end instead. And when the rewrite inserts or removes a group separator, every offset the user was aiming at shifts underneath them: a backspace aimed at a digit takes the separator, the formatter re-derives the string from what is left, and a digit is gone for good.

So the field fights the person entering the value, on every keystroke, in exchange for a cosmetic benefit that nobody needs until the value is final.

Entry is read-only; grouping belongs to blur

The rule we settled on is that the field does not rewrite text while the value is moving. Grouping gets applied on blur, once it has stopped. That is the policy encoded in the state machine behind amountfield, our React money input, and the comment in src/field.ts carries the whole argument. Regrouping mid-typing is what makes a field jump the caret and eat a digit, so we leave that to blur.

The state the field carries is deliberately wider than a string and a value:

export type FieldState = {
  /** What the input element shows. Always what the person typed, until blur. */
  readonly text: string;
  /** The exact amount, when the text is a complete one. */
  readonly money: Money | null;
  /** Why there is no amount. Null while the field is simply incomplete. */
  readonly problem: ParseFailure | null;
  /** True when the text is a prefix of a valid amount rather than wrong. */
  readonly incomplete: boolean;
  /** Where the caret belongs in `text`, after whatever rewrote it. */
  readonly caret: number;
};

text and money are separate fields because they are separate jobs. The text belongs to the person typing. The amount is exact minor units held in parallel, and the two do not need to agree on presentation at any point during entry:

const eur = { currency: "EUR", locale: "en-US" };

let state = typed("1234.5", eur);
// state.text  === "1234.5"      <- untouched, mid-entry
// state.money                   <- 123450 minor units, already exact

state = blurred(state, eur);
// state.text  === "1,234.50"    <- the one rewrite we chose

The value was never ambiguous while the text sat half written. Deferring the formatting costs nothing in correctness, because the amount never came from the pretty string in the first place.

When a rewrite is unavoidable, count what the person is aiming at

Two rewrites survive the rule. Blur applies grouping, and a paste has to be cleaned up, because a money field cannot hold its own currency symbol beside the number. We keep sanitising as narrow as it can be:

export function sanitise(text: string, options: FieldOptions): string {
  const currency = normalizeCurrency(options.currency);
  const locale = options.locale ?? "en-US";

  let cleaned = text.replace(MINUS, "-");
  for (const mark of marksFor(currency, locale)) cleaned = cleaned.split(mark).join("");
  cleaned = cleaned.replace(new RegExp(currency, "gi"), "");

  return cleaned.replace(/^\s+/, "");
}

A field that then drops the caret at the end is worse than one that never reformats at all, because now the text moves and the user has no model of when. So we make the caret policy explicit: the digits, the sign and the decimal point are what the person is aiming at, while grouping, spaces and symbols move around them. The caret goes back after the same count of the former. In practice:

1234.5^ on blur becomes 1,234.5^0, not 1,234.50^. Six aimed-at characters before the caret, still six after.
^1234 becomes ^1,234. Zero before the caret, so it stays in front of the number once the number grows a separator.
€ 1.234,^56 pasted into a EUR field becomes 1.234,^56. The symbol and the no-break space behind it vanish in front of the caret, and the caret comes back with them gone.

This is also why useAmountField asks you to spread inputProps rather than pick fields out of it. The ref it carries is how the caret actually gets restored after React has written the new value into the DOM node:

function PriceField() {
  const field = useAmountField({ currency: "EUR", locale: "de-DE" });
  return (
    <>
      <input {...field.inputProps} />
      {field.problem && <span role="alert">{field.problem}</span>}
    </>
  );
}

Not finished yet has to become a real state

Leaving the text alone during entry forces a distinction that a reformat-on-keystroke field never has to make. 12. is twelve on the way to 12.00. 12,5 in a de-DE field is twelve fifty with the last digit still missing. 1 2 in fr-FR is a group that has not reached three digits. A lone - is on its way to -5. None of these parse, and none of them are mistakes.

That is what incomplete is for, and why it sits apart from problem. The first means the text is a prefix of a valid amount, the second means it is wrong. aria-invalid in inputProps follows problem and not incomplete, so the field does not announce itself as invalid between the . and the 5 of 12.50.

The refusals are still refusals. 12.345 in a two-decimal currency comes back too-many-decimals. 12.34 typed into a de-DE field comes back bad-grouping rather than being read as 1234.00, because the dot is a decimal point written with the wrong separator far more often than it is a thousands mark on a two-digit number. $12.34 pasted into a EUR field keeps its dollar sign (only the field's own currency is stripped) and gets refused as not-a-number rather than quietly taken for euros. A field that leaves the text alone mid-entry can afford to be strict at the edges, because strictness no longer lands on someone who is simply still typing.

The caret is testable because the logic is not in the component

All of this is a pure function, and the hook is a thin wrapper over it. That is not architectural taste. An input's awkward cases (a half-typed 12., a pasted 1 234,56, a caret in the middle of the number) are exactly what nobody tests when the logic only exists inside a component, and the caret is the first thing to rot in a refactor, probably because nothing fails loudly when it moves.

With the state machine outside React, the caret is an assertion like any other. typed takes the position the input element left the caret at and returns where it belongs:

const eur = { currency: "EUR", locale: "en-US" };

const pasted = typed("\u20ac1234", eur, 3);
// pasted.text  === "1234"   the field's own symbol is stripped
// pasted.caret === 2        two digits were in front of it, two still are

const grouped = blurred(typed("1234.5", eur, 6), eur);
// grouped.text  === "1,234.50"
// grouped.caret === 7        after the "5", not after the appended "0"

Those two cases are the regression test for the entire argument of this post, and they run in milliseconds without a DOM.

What it costs to run

Three things, and they are worth naming before you adopt the pattern.

You hold a caret in state and own a ref. That is unavoidable if you intend to rewrite text at all; the alternative is not holding it and losing it.

Blur becomes semantically meaningful. A form that submits without the field losing focus has to read field.money, which is exact from the first complete keystroke, rather than parsing the displayed text. Resets come through setMoney rather than by writing a formatted string in.

And you carry three states in your UI instead of two: valid, wrong, and not finished. Most of the design work in a calm money field sits in that third one.

The formatting itself is cheap. Intl formatters and the separators for a locale are built once and cached per key, and grouping now happens on blur rather than on every keystroke, so the field does strictly less work than the version that eats digits.

None of this makes a money field interesting. It makes it quiet, and quiet is the whole specification: the number the user typed is the number that is there, and the caret is where they left it.

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

Where a discount belongs: the invoice or the line, never both

Shipmind Labs — Tue, 06 Oct 2026 13:24:03 +0000

An invoice can agree with itself in every direction and still be the wrong document. The case that survives validation is a discount granted once and recorded twice, once as a line level allowance and again at document level. The second copy moves every derived total along with it, so there is no arithmetic left for a business rule to object to. The neighbouring mistakes are loud: a discount left out of the line net amount, or a percentage that does not match the base amount it claims to be a percentage of, get refused on sight. The duplicate is quiet. That asymmetry is what turns placement into a design decision rather than a detail.

We build and maintain invoicerules, a TypeScript library that checks a document against the EN 16931 business rules before a tax platform does. This is the failure we point at when a client asks what validation cannot do for them.

Two homes, and they are not interchangeable

The standard gives a discount two places to live, and the difference is not cosmetic. The model types carry the distinction explicitly:

/**
 * BG-27 / BG-28: a line level allowance or charge. It 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 (BT-131) that the totals
 * and the VAT breakdown are built from.
 */
export type LineAllowanceCharge = {
  readonly amount: Amount;
  readonly baseAmount?: Amount;
  readonly percentage?: string;
  readonly reason?: string;
  readonly reasonCode?: string;
};

/**
 * BG-20 / BG-21: a document level allowance or charge. The amount is always
 * positive; which list it is in decides whether it is taken off or added on.
 * It carries a category and a rate because it belongs to a VAT breakdown
 * group, not to the invoice as a whole.
 */
export type AllowanceCharge = {
  readonly amount: Amount;
  readonly baseAmount?: Amount;
  readonly percentage?: string;
  readonly vatCategory: VatCategory;
  readonly vatRate: string;
  readonly reason?: string;
  readonly reasonCode?: string;
};

A line level discount has no category because it does not need one. It is subtracted inside the line, and it reaches the totals and the VAT breakdown only through the line net amount, BT-131, which is quantity times price less the line's allowances and plus its charges. A document level discount carries a category and a rate because it is summed into BT-107 and moves the taxable amount of the breakdown group it names. That is also why the breakdown check insists the group exists at all, and reports a missing one as BR-CO-18 against allowances[n].vatCategory.

So the two placements are two different claims about what was discounted. They happen to agree on the money whenever a single breakdown group is involved, and that coincidence is where the trouble starts.

One discount, four documents

Take one line: ten units at 100.00 net, standard rate at 23%, and a 50.00 discount granted once. Four ways to record it:

Where the 50.00 goes	Line net (BT-131)	Allowance total (BT-107)	Taxable (BT-116)	VAT (BT-117)	`totals.payable`	Validator
On the line	950.00	n/a	950.00	218.50	1168.50	passes
At document level	1000.00	50.00	950.00	218.50	1168.50	passes
Both	950.00	50.00	900.00	207.00	1107.00	passes
On the line, but BT-131 not reduced	1000.00	n/a	1000.00	230.00	1230.00	refused

The first two rows are the same invoice. That is the useful fact and the dangerous one: both correct placements produce an identical payable amount, so nobody downstream can tell you which one you meant, and nobody has to.

The fourth row is the easy bug. The line carries an allowance, the stated net amount still equals quantity times price, and the derived value disagrees with the document. The discount hides from the totals and from the VAT breakdown both, so the check on the line net amount refuses the document. It gets reported under the Peppol identifier, because EN 16931 leaves that arithmetic to the syntax binding and the Peppol identifier is the one a receiver will quote back at you.

The third row is the one that ships. The document is internally perfect: the line total matches the lines, the allowance total matches the document level allowances, the taxable amount is the line total less the allowance, the VAT is 23% of that taxable amount, the inclusive total and the payable amount follow. Every one of those is a rule, and every one of them passes. The invoice is 61.50 light (the discount a second time, plus the 23% that was never charged on it), and it describes a sale that did not happen.

What a coverage report can and cannot tell you

validate returns more than a boolean. You get every rule that was evaluated, how it came out, and the element it looked at, named both as the model field and as the path the element has in the document that gets sent. On the duplicate, the interesting part is the monotony.

import { validate } from "invoicerules";

const result = validate(duplicated);
result.ok; // true

["BR-CO-10", "BR-CO-11", "BR-CO-13", "BR-CO-14", "BR-CO-15", "BR-CO-16"].map(
  (rule) => result.coverage.find((c) => c.rule === rule)?.outcome,
);
// [ "pass", "pass", "pass", "pass", "pass", "pass" ]

A rule with nothing to check is absent from the report rather than counted as a pass, so the coverage list is an honest account of what was actually looked at. Read it with that in mind and the gap is plain: nothing in it asks whether this allowance and that one describe the same commercial fact. No rule can. BT-107 is a number and BT-131 is a number, and the duplicate makes both of them true.

toUBL throws unless the rules pass, which stops the fourth row from ever leaving the building. It writes the third row without a word.

Decide once, in the builder's type

If validation cannot refuse the document, then the document has to be impossible to build. We keep one representation of a discount above the library, with a tag that answers the placement question exactly once:

import type { AllowanceCharge, Amount, Line, LineAllowanceCharge, VatCategory } from "invoicerules";

/** Whole minor units, our representation before the document exists. */
type Minor = number;

const toAmount = (minor: Minor): Amount =>
  `${Math.trunc(minor / 100)}.${String(minor % 100).padStart(2, "0")}`;

type Discount =
  | {
      readonly scope: "document";
      readonly amount: Minor;
      readonly vatCategory: VatCategory;
      readonly vatRate: string;
      readonly reason: string;
    }
  | {
      readonly scope: "line";
      readonly lineId: string;
      readonly amount: Minor;
      readonly reason: string;
    };

type RawLine = {
  readonly id: string;
  readonly name: string;
  readonly quantity: number;
  readonly netPrice: Minor;
  readonly vatCategory: VatCategory;
  readonly vatRate: string;
};

function lineOf(raw: RawLine, discounts: readonly Discount[]): Line {
  const mine = discounts.filter((d) => d.scope === "line" && d.lineId === raw.id);
  const net = mine.reduce((running, d) => running - d.amount, raw.netPrice * raw.quantity);
  const allowances: LineAllowanceCharge[] = mine.map((d) => ({
    amount: toAmount(d.amount),
    reason: d.reason,
  }));
  return {
    id: raw.id,
    name: raw.name,
    quantity: raw.quantity,
    netPrice: toAmount(raw.netPrice),
    netAmount: toAmount(net),
    vatCategory: raw.vatCategory,
    vatRate: raw.vatRate,
    allowances,
  };
}

function documentAllowances(discounts: readonly Discount[]): AllowanceCharge[] {
  return discounts
    .filter((d) => d.scope === "document")
    .map((d) => ({
      amount: toAmount(d.amount),
      vatCategory: d.vatCategory,
      vatRate: d.vatRate,
      reason: d.reason,
    }));
}

The two functions partition the same list. A discount with scope: "line" is read by lineOf and is invisible to documentAllowances, and the reduction that produces netAmount is the same traversal that produces the line's allowance list, so the discount cannot be present in one and missing from the other. Getting the third row of the table now takes two Discount objects, which is a different commercial fact, visible at the point where someone has to type it.

The tag also forces a question the arithmetic was hiding. On a mixed basket the two placements stop agreeing: a document level discount must name a category and a rate, so it either belongs to one breakdown group or has to be split across groups, while a line level discount simply inherits its line's category. "Which group does this discount reduce" has a commercial answer rather than a technical one, and the union is where you record it instead of guessing.

Prove both paths against each other

The test that earns its keep is probably the differential one. Build the same discount both correct ways and assert the documents agree, then assemble the duplicate by hand and assert that it validates and is still wrong.

import test from "node:test";
import assert from "node:assert/strict";
import { validate } from "invoicerules";

const basket: readonly RawLine[] = [
  { id: "1", name: "Support retainer", quantity: 10, netPrice: 10_000, vatCategory: "S", vatRate: "23" },
];

test("one discount, two placements, one document", () => {
  const onLine = build(header, basket, [
    { scope: "line", lineId: "1", amount: 5_000, reason: "Volume" },
  ]);
  const atDocument = build(header, basket, [
    { scope: "document", amount: 5_000, vatCategory: "S", vatRate: "23", reason: "Volume" },
  ]);

  assert.ok(validate(onLine).ok);
  assert.ok(validate(atDocument).ok);
  assert.equal(onLine.totals.payable, atDocument.totals.payable);
  assert.equal(onLine.totals.payable, "1168.50");
});

test("the duplicate validates and is still the wrong amount", () => {
  const onLine = build(header, basket, [
    { scope: "line", lineId: "1", amount: 5_000, reason: "Volume" },
  ]);
  const duplicated = withDocumentAllowance(onLine, {
    amount: "50.00",
    vatCategory: "S",
    vatRate: "23",
    reason: "Volume",
  });

  assert.ok(validate(duplicated).ok);
  assert.notEqual(duplicated.totals.payable, onLine.totals.payable);
});

build fills the breakdown with computeVatBreakdown and derives the totals from it, so the first test is checking the whole chain from discount to payable amount. The second test needs a helper to reach around the builder and re-derive the totals, because the duplicate is unreachable through build. That is the result we wanted, written down as a test rather than as a convention. If someone later adds a second path where discounts enter the draft, that assertion is the thing that stops passing.

What it costs to run

A tagged union, two filters, and a fixture built twice. The ongoing cost is the rule that discounts enter the draft in exactly one place, which is a review habit rather than a test. Our review gate exists to catch that kind of thing, because no validator on either side of the wire will.

Worth keeping separate in your head: the loud placement bugs are the library's job, and the duplicate is yours. The only external check that would catch the third row is the counterparty comparing the payable amount against their own order, and by that point the invoice has been accepted by a platform and cleared, so the correction is a credit note rather than an edit.

Close

A discount is one fact with two legal spellings. Pick the spelling in the type, derive both the line net amount and the allowance total from that one decision, and keep a validator in front of the send so the spellings that are merely wrong never reach a platform. The document that adds up and still lies is the one you have to make unbuildable.

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

Order per entity, not per queue, in an offline write queue

Shipmind Labs — Mon, 05 Oct 2026 13:24:03 +0000

An offline write queue has to honour two rules that pull against each other: two changes to the same record have to arrive in the order the user made them, and one stuck change should not hold unrelated work hostage behind it. A single global FIFO queue gives you the first and not the second. A queue that fires everything at once gives you the second and quietly corrupts the first. Neither shape is a tuning problem. Both are missing the same fact.

The constraint: the queue does not know what a change touches

We build mobile clients where writing offline is ordinary rather than exceptional, role-specific apps for couriers and warehouse staff, where the signal goes away between a loading dock and a basement and the work carries on without it. What you notice first in that setting is that ordering is not a property of the queue. It is a property of a pair of changes.

Edit the title of note 42, then delete note 42: the order decides what the server ends up holding. Upload a photo, then star a different note: the order does not matter, and insisting on it means the star waits behind a multi-megabyte upload on a cell edge. A queue that sorts only by the time a change was enqueued has thrown away the one fact that separates those two cases, which is what the change touches. That fact lives in the app's domain model and not in the transport, and no amount of poking at the request body gets it back.

So in our queue (https://github.com/shipmindlabs/offlinequeue) the caller names it:

const entityOf = (operation: Operation) =>
  (operation.payload as { note?: string }).note ?? operation.kind;

const queue = new OfflineQueue({
  storage: keyValueStorage(AsyncStorage),
  send,
  entityOf,
  concurrency: 4,
});

entityOf returns a string, and that string is the lane. Changes that return the same string go out in the order they were made; changes that return different strings do not wait for each other. When the app supplies nothing, the default is operation.kind, which orders a change against every other change of its kind. That default is correct and coarse on purpose: it does not reorder anything, and it serialises two unrelated notes behind each other, which is exactly the trade you should be able to see and then improve on.

A lane stops at the first change that has to be retried

The tempting optimisation inside a lane is to step over the change that failed and try the next one, so the flush gets some work done. That optimisation is the bug:

const seen: string[] = [];
const q = queue(async (operation) => {
  seen.push(operation.kind);
  return { result: "retry", reason: "offline" };
});
await q.enqueue("title", { note: "42", title: "Dinner" });
await q.enqueue("remove", { note: "42" });

const report = await q.flush();

assert.deepEqual(seen, ["title"], "the delete does not overtake the edit it follows");
assert.equal(report.retrying, 1);

If the title edit stays on the device and the delete goes out, the server sees a delete for a note whose edit arrives afterwards. What happens next is not ours to decide: depending on how the write is implemented, the late edit either fails on a missing row or recreates the record the user deleted. Users report both outcomes as the app losing their work, and neither one reproduces without the exact pair of timings that produced it.

So head-of-line blocking inside a lane is not a flaw to be optimised away. It is the guarantee, stated in terms of a storage state. You bound the cost of it by making lanes narrow, not by stepping over the head. The change at the head is left pending with a nextAttemptAt in the future, the delay doubles from baseDelayMs under a maxDelayMs ceiling, and the jitter is drawn per change so that every phone that lost the same cell tower does not retry in the same instant.

Lanes never wait for each other, up to a limit

Once the entity is named, the stuck lane is only as wide as the record it belongs to:

await q.enqueue("edit", { note: "1", text: "first" });
await q.enqueue("edit", { note: "1", text: "second" });
await q.enqueue("edit", { note: "2", text: "unrelated" });

const report = await q.flush();

assert.equal(report.sent, 1, "the unrelated note went out");
assert.equal(report.retrying, 1);
assert.deepEqual([...seen].sort(), ["1", "2"], "the second change to note 1 waited");

The second edit to note 1 waited, because it had to. Note 2 went out, because nothing said it should not.

A flush runs several lanes at once, up to concurrency, four by default, and that bound is there for the radio and the server rather than for correctness:

const lane = gated(2);
for (const note of ["1", "2", "3", "4"]) await lane.q.enqueue("edit", { note });

const flushing = lane.q.flush();
await settle();
assert.equal(lane.started.length, 2, "two entities are on the wire, not four");

lane.open();
const report = await flushing;
assert.equal(report.sent, 4, "the rest went out as the first two finished");

The property worth stating out loud, because it is what makes the setting safe to change: concurrency limits how many unrelated changes are in flight together, and it is not a way for two changes to one entity to overtake each other. Raising it cannot break ordering. It can only press harder on a weak connection and on the server. Lowering it to one is still correct, since entities then go one at a time, slowly, and in order.

Parking is the one place we give up ordering on purpose

The transport answers with one of three outcomes: done, retry, or rejected. The distinction between the last two is what keeps a lane from freezing for ever. retry means try again, so the lane stops. rejected means the server will not accept this change, so stopping the lane behind it helps nobody:

await q.enqueue("title", { note: "42", title: "" });
await q.enqueue("star", { note: "42" });

const report = await q.flush();

assert.deepEqual(seen, ["title", "star"], "the lane carries on past the parked change");
assert.equal(report.rejected, 1);
assert.equal(report.sent, 1);

This is worth being honest about rather than presenting as free: stepping past a parked change does reorder it against the rest of its lane. We accept that, because the alternative is a lane that is dead until the app is reinstalled, and because a refusal is not something the queue can fix. A change that merely ran out of attempts is parked the same way, for the same reason, since a delay that doubles for ever is still a queue that does not stop trying.

What the queue owes you in exchange is that the parked row stays in storage, keeps its parkedReason and lastError, and is reachable from a screen through failed. From there the ways out are retry(id), which returns it to pending, and discard(id), which removes it. Deliberately not a second enqueue, which would hand back the parked row and look like it had worked. The idempotency key is generated on the device and does not change across retries, so a change that sits parked for days and is then retried is still recognisable to the server as the same change.

What it costs to run

The one real decision is the granularity of entityOf, and it has a failure mode on each side. Too coarse and the app serialises work that has no relationship, every note behind every other note, which is what the kind default does. Too fine and two changes that genuinely depend on each other land in different lanes and can arrive backwards, which is the original bug with extra steps. The rule we apply is to make the entity the thing the server's write actually contends on, usually the row being updated. When a change touches two entities, it is named after the one whose ordering cannot be lost, or it is split into two changes.

The rest is cheap and worth knowing. Every state transition is persisted, so a flush writes to storage; enqueueing a key the queue already holds changes nothing and therefore writes nothing. leaseMs has to be longer than the slowest request the transport permits, since it is the period after which an attempt is presumed to have died with its process; load reclaims those on the way in. And FlushReport carries sent, rejected, exhausted, retrying and remaining as separate fields precisely because a badge, a spinner and a "needs your attention" list are three different questions.

None of this needs a device to test. The ordering rules above are assertions about which requests a fake transport saw, and in which order, which is why they are regression tests rather than things we re-learn in the field.

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

A deep link that arrives before login: park it, replay it once, expire it

Shipmind Labs — Sun, 04 Oct 2026 13:24:11 +0000

Sometimes a link arrives before the app can do anything with it. A cold start resolves the URL that opened the process before the navigator exists, and a link into a screen behind a login arrives while nobody is signed in. The destination is known and valid in both cases. What is missing is somewhere to put it until the app can actually go there. The two usual answers (a module-level variable and a timeout) both replay the link at the wrong moment: twice, or twenty minutes late.

We build role-specific mobile apps and the notification fan-out behind them, web and mobile push plus chat channels, so almost every link we route was tapped from outside the app by someone whose session state we do not control. The signed-out tap is the normal case here, not the edge case. This post is about the small piece of state that case produces, and the three separate deadlines it needs. The code is from deeplinkmap, the deep-link router we maintain at https://github.com/shipmindlabs/deeplinkmap.

Two moments, one shape

A running app is handed links by an event. A starting app has to ask for the one that opened it, and that answer lands early, before the navigation tree is mounted and usually before the stored session has been read back from disk. Navigating then either throws or navigates nothing. The link is gone.

The second moment has nothing to do with startup. A link to an order, a receipt, a document waiting for a signature is a link to a screen behind a login. Open it anyway and the screen either fails oddly or renders with no session, which is worse: that is a screen nobody was supposed to reach without one.

Both are the same shape. The destination resolved cleanly, the app cannot use it yet, so it has to be held. Everything that goes wrong afterwards is a property of that hold, not of the parsing and not of the navigator.

We have written here before about why most of a deep-link router's safety is bought at construction time, when the table either refuses to build or hands back a named refusal. This is the part that comes after a clean match.

One door, so the hold is fed once

Before anything is held, both delivery paths have to meet. A cold start can deliver the same URL through both of them, a url event can fire twice for a single tap, and a notification reopened from the tray repeats the URL it carried. Two handlers also drift, and one of them ends up missing a check the other has.

import { LinkIntake, PendingLink, Router, type Delivery } from "deeplinkmap";

const intake = new LinkIntake(router);
const pending = new PendingLink();

Linking.getInitialURL().then((url) => handle(intake.start(url)));
Linking.addEventListener("url", ({ url }) => handle(intake.deliver(url)));

function handle(delivery: Delivery | null) {
  if (delivery === null || delivery.status === "duplicate") return;
  if (delivery.status === "refused") return; // the audit hook has it

  const { match } = delivery;
  if (match.requiresAuth && !session) {
    pending.hold(match);
    return;
  }
  navigate(match);
}

start() takes whatever the initial-URL lookup resolved to, including nothing, because no link is not a delivery. Everything else goes through deliver(). A link already seen inside dedupeWithinMs (three seconds by default) comes back as a duplicate and is not applied again, and that dropped repeat goes to the same audit hook as every acceptance and refusal, so one log holds every decision.

Two details in that window are deliberate. Links are compared as received, so two different URLs are two links even when they end up on the same screen, because folding them together would suppress a link somebody meant to send. The window is also anchored to the first sighting, which keeps a burst of repeats from pushing it out and hiding the link indefinitely.

Three seconds is chosen the way these numbers usually are: long enough to swallow a double-fire, short enough that a person deliberately tapping the same link again gets the screen. A window of zero remembers nothing, and a window with no end makes a second tap an hour later do nothing at all, so both throw InvalidIntake at construction rather than reading as dedupe and behaving as something else.

The hold stores the decision, not the URL

hold() takes a Match, not a string, and that matters more than it looks. By the time the match exists, the host has been checked against the ones this app owns, the door the link came through has been checked against the ones the route opens to, every placeholder has been validated against its declared kind, and the whole decision has already gone to the audit hook. Replaying a Match does not re-open any of those doors.

Holding the raw URL instead means re-resolving it later, against a table that may have been rebuilt in between, and producing a second audit entry for the same link. The hold is the answer, already given.

function onSignedIn() {
  const resumed = pending.take();
  if (resumed) navigate(resumed);
}

function onSignedOut() {
  pending.clear();
  intake.clear();
}

The single-use property lives in five lines:

take(): Match<Name> | null {
  const match = this.#fresh();
  this.#held = null;
  return match;
}

The hold is released before the destination is handed back. A login callback that fires twice, a screen that remounts, a second take() from a different effect: each of them gets null. That is the difference between a resume and a loop. You consume the hold, you do not simply read it.

A newer link replaces an older one, because the last thing the person tapped is the thing they meant. clear() exists for sign-out: a destination held for one session must not be replayed into the next one.

A hold without an end is a surprise waiting to happen

A link acted on twenty minutes late is not a resume. The person tapped it, waited, gave up, and started using the app for something else, and navigating them away at that point is worse than dropping the link. So a hold has a lifetime (expiresAfterMs, ten minutes by default), and when it is over the held match is dropped rather than hidden.

const expiresAfterMs = options.expiresAfterMs ?? DEFAULT_EXPIRES_AFTER_MS;
if (!Number.isFinite(expiresAfterMs) || expiresAfterMs < 1) {
  throw new InvalidHold(
    `expiresAfterMs ${expiresAfterMs} is not a lifetime a link can be held for`,
  );
}

Zero drops every link the moment it is held, and a lifetime with no end is exactly the replay-much-later surprise the expiry exists to prevent. Both read as a hold and behave as something else, so construction accepts neither.

The freshness check also refuses a clock that moved backwards. A timezone trip or an NTP correction produces a negative elapsed time, and a naive comparison would extend the hold by the size of the correction instead of ending it. Treating backwards as expired is the conservative direction, because the worst case there is a dropped link rather than a link replayed an hour late.

One consequence worth knowing: reading waiting runs the same check, so observing a stale hold is what drops it. No code path leaves an expired link visible.

Three different kinds of once

The mechanisms look similar and answer different questions, and collapsing them into one is how these bugs come back.

mechanism	span	question it answers
intake dedupe window	seconds (3 by default)	is this the same delivery arriving twice?
`take()` releasing before it returns	once, ever	has this destination already been applied?
`expiresAfterMs`	minutes (10 by default)	is this still what the person meant?

A dedupe window cannot stop a resume loop, because the second take() can happen minutes after the first. Single-use cannot stop a duplicate delivery, because two deliveries are two holds. And neither one makes a link stale.

Testing it without a device

The hold reads the clock through an injected now, which turns every timing rule into an ordinary unit test. No device, no sleeping test suite.

test("a held link is dropped once its lifetime is over", () => {
  let at = new Date("2026-08-16T10:00:00Z").getTime();
  const pending = new PendingLink({ expiresAfterMs: 60_000, now: () => new Date(at) });

  pending.hold(matched("https://example.com/order/5"));
  at += 30_000;
  assert.equal(pending.waiting, true);

  at += 60_000;
  assert.equal(pending.waiting, false);
  assert.equal(pending.take(), null);
});

The clock-moving-backwards case is the same test with a subtraction. This is the part of our review gate we do not negotiate on for anything timing-dependent: if a rule is about elapsed time, the time source is a parameter.

What it costs to run

One slot of memory for the hold, plus a map of recently seen URLs that is pruned on each delivery. No timers, no background work, nothing to configure per environment. The router imports nothing from React Native, so all of this runs in a plain Node test process.

The hold does not survive the process being killed, and that is a decision rather than an omission, since a link held across a relaunch is on its way to being the twenty-minutes-late replay. If a particular flow genuinely needs to survive a restart, the thing to persist is the match together with the timestamp it was held at, and then the expiry is the only reason the stored link is not a trap.

The operational surface is the audit hook. Refusals and dropped duplicates are the two lines worth watching: a steady stream of foreign-host refusals is an app being probed with links to hosts it does not own, and a jump in duplicates probably means a delivery path was wired twice.

Close

A deep link that arrives too early is a small amount of state, and almost all of the bugs around it are deadline bugs rather than routing bugs. Park the decision. Release it before you hand it back. Give it a lifetime short enough that a replay is still a resume. Each of those has to be stated separately, because no one of them implies the others.

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

Make a staging OTP shortcut fail at startup, not at verification

Shipmind Labs — Sat, 03 Oct 2026 13:24:10 +0000

A fixed code that opens every account is the fastest way to test a login flow, and a breach on the day it reaches production. The awkward part is that the verification function cannot catch this: by the time a candidate string arrives, the only question left is whether it matches, and a universal code matches. The defence has to sit earlier, in the code that reads the environment and in the code that wires the application together.

We build and run authentication flows for systems where a login is the door to money, so we had to decide where a convenience like this is allowed to live. Our answer is that it may exist, but only as an object you can interrogate before the first request is served. We maintain a small library for this, otpguard, and the test-mode module is the part we argued about most.

The check is the wrong place to put the question

The usual shape of this bug is a conditional inside the verification path:

if candidate == settings.OTP_TEST_CODE and settings.DEBUG:
    return True

Two separate things go wrong here, and only one of them is about the comparison. The first is that an environment question, is this deployment allowed to have a bypass, gets answered per request, inside an authentication decision, with nobody watching. The second is that the answer leans on a flag that is routinely wrong in exactly the deployments where it matters: a staging-like box promoted to serve real traffic, a container that inherited an env file, a DEBUG that defaults to true in a path nobody audited.

So we moved the question to two moments that happen once, loudly, and before any user is involved: when the mode is constructed from the environment, and when the application assembles its dependencies.

Constructing the mode is where the environment gets interrogated

TestMode is off unless you pass a code, and you cannot pass a code without a lifetime:

from datetime import timedelta
from otpguard import TestMode

TestMode()                                  # off
TestMode("424242")                           # ValueError: test mode must expire
TestMode("424242", ttl=timedelta(days=7))    # ValueError: ttl must not exceed 1 day
TestMode("424242", ttl=timedelta(hours=1))   # armed, and logs at CRITICAL

MAX_TEST_MODE_TTL is twenty-four hours, and it is a ceiling rather than a default. Whatever the caller asks for, a universal code cannot outlive a working day, so a bypass left in an environment file stops being a credential on its own, without anyone remembering it. Passing a ttl with no code is an error too, not a no-op, because a half-removed configuration is something we would rather hear about than quietly honour.

Reading the same settings from the environment goes through from_env, which is where the deployment gets to disqualify itself:

import os
from otpguard import (
    ENVIRONMENT_VAR,
    TEST_MODE_CODE_VAR,
    TEST_MODE_TTL_VAR,
    TestMode,
)

TestMode.from_env({})                                 # off
TestMode.from_env({TEST_MODE_CODE_VAR: "   "})        # off: a blank code is no code

env = {
    TEST_MODE_CODE_VAR: "424242",
    TEST_MODE_TTL_VAR: "600",
    ENVIRONMENT_VAR: "Production",
}
TestMode.from_env(env)                                # TestModeInProduction

mode = TestMode.from_env(os.environ)                  # the real call site

PRODUCTION_ENVIRONMENTS holds live, prod and production. That list is deliberately small and dumb. It is not a security boundary, since an environment can call itself anything, but it does catch the most common version of the accident, which is a value copied between env files along with everything else. A deployment that announces itself as production and also carries a universal code has told you two contradictory things, and the library refuses to settle that contradiction in favour of convenience.

The guard asks whether it is configured, not whether it works

The second moment is wiring, and the function there is require_no_test_mode. Its rule is narrower than it first looks: it raises while a universal code is configured at all, expired or not.

import pytest
from datetime import timedelta
from otpguard import TestMode, TestModeInProduction, require_no_test_mode

def test_a_configured_mode_is_refused_where_it_must_not_exist():
    with pytest.raises(TestModeInProduction):
        require_no_test_mode(TestMode("424242", ttl=timedelta(hours=1)))

def test_a_mode_that_is_off_passes_the_guard():
    mode = TestMode()
    assert require_no_test_mode(mode) is mode

Letting an expired mode through the guard would be the wrong behaviour, and the reason is operational rather than cryptographic. An expired universal code is still a value sitting in a deployment's configuration, still travelling through whatever pipeline put it there, still one TTL bump or one clock argument away from being live again. is_active() is a question about now, while is_configured is a question about the deployment. Startup cares about the second one.

That makes the wiring code boring, which is what we want from it:

import os
from otpguard import TestMode, require_no_test_mode, require_real_sender

def build_code_flow(settings, sender):
    mode = TestMode.from_env(os.environ)
    if settings.is_production:
        require_no_test_mode(mode)
        require_real_sender(sender)
    return mode, sender

Note that settings.is_production here is the application's notion of production, not the library's. The two checks are redundant on purpose: from_env refuses a deployment that names itself production, and the guard refuses a mode however it was built, including one constructed in code, in a test fixture that escaped, or under an environment name the library has never heard of.

The same shape for anything that only pretends

A universal code is one member of a family: development objects that accept real input and produce no real effect. The other one in this library is StubSender, which keeps messages instead of delivering them so that local runs and tests can read the code back. Left in a deployment it accepts every code and delivers none of them, which is the same failure wearing different clothes, an auth flow that appears to work and verifies nothing.

So it carries the same two properties. It admits what it is with a is_stub = True marker that callers can ask about without knowing the concrete type, and there is a guard with the same signature:

from otpguard import StubSender, StubSenderInProduction, require_real_sender

require_real_sender(StubSender())
# StubSenderInProduction: StubSender delivers nothing; configure a real sender

When the two guards share one shape, you can read the startup block above as a single policy, this deployment uses nothing that pretends, rather than as two unrelated checks someone might implement only half of.

Three log levels, and a repr that keeps the secret

Arming the mode logs at CRITICAL, naming the moment it expires. Every accepted universal code logs at ERROR, stating that no stored code was verified. A code offered after expiry is refused and logged at WARNING. Those levels are not for the developer who turned it on. They are for whoever is grepping a production log months later and needs the arming event, the uses, and the probes to be three distinguishable things.

Two details make the logs trustworthy. First, verification tries the stored digest before it considers the universal code, so a real code produces no test-mode log line at all and the bypass cannot shadow a genuine one:

mode.verify(candidate, stored, pepper=SERVER_SECRET)

Second, the secret stays out of everything that gets printed. repr(TestMode()) is TestMode(off), an armed mode's repr does not contain the universal code, and Message renders its code as '***', because a live code in a traceback is a code someone else can use.

What it costs to run

Less than the conditional it replaces, with one honest exception. At startup you read the environment once and build an object. At verification you pass that object instead of calling a module-level function. Nothing is added to the request path, and the verification call stays unconditional, which is the main win: there is no if DEBUG branch left to be wrong.

The cost is that staging has to re-arm at most daily, because the TTL ceiling will not let a bypass sit there for a sprint. We consider that the feature. The other cost is real and worth planning for, because a deployment that carries a universal code into production now refuses to start. That has to show up in the pipeline as a failed release with a readable message, not as a container restarting in a loop that nobody is watching. The exception text is written for that moment, test mode must not be configured here followed by the reason, since the person reading it is probably mid-incident and did not write the config.

A bypass you can ask about, that expires on its own, announces itself three ways and can stop the process, is still a bypass. It is no longer a credential with no owner and no end date. The convenience is allowed to exist. Existing quietly is the part that is not.

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

An unanswered question is not a no

Shipmind Labs — Fri, 02 Oct 2026 13:24:12 +0000

A compliance checklist made of tick boxes has exactly two states, and an empty box reads as "no". That is a quiet way to ship a chatbot without its disclosure: nobody ever decided whether the system speaks directly to people, and the form decided it for them, in the direction that creates no work.

We hit this while building disclosurekit, a small TypeScript package that works out which of the transparency duties in Article 50 of the EU AI Act apply to a system, what a notice has to get across, and where it has to appear. The rules themselves are short, five rows in one table. The decision procedure over them is simple enough. The input is where it gets awkward: a description of your own system, put together by someone who does not know all of it.

The missing answer is the normal case

When we started writing down the inputs an assessment needs (does this system interact directly with people, does it generate synthetic content, is any of it a deep fake of real people, is emotion recognition in the path, are we the provider or the deployer) we expected the uncertain answers to be rare. They are not rare. They are the normal condition of a system in the middle of its life.

The backend team knows whether a model output reaches an end user unmediated. Whether the vendor whose model sits behind the feature counts us as a provider or a deployer is a question for whoever read the contract. Whether the generated images in a product listing are a deep fake of a real place is a question nobody has been asked yet. Each of these has a correct answer. None of them has an answer at the moment the assessment runs.

A boolean field cannot hold that situation. It holds true, false, and the absence of the key, and the absence of the key is where every uncertain answer ends up, because the person filling in the form had nothing to put there. The library then applies the only reading a two-state input allows, decides the duty does not bite, and returns a clean result. That is the failure mode we care about: not a wrong answer that looks wrong, but a wrong answer that looks finished.

Three states in, three buckets out

So the input type admits "unknown", and the output has somewhere to put it.

import { assess } from "disclosurekit";

const profile = {
  role: "provider",
  interactsWithPeople: "unknown",
} as const;

const result = assess(profile);
// Article 50(1) is not in the applied duties and not in the excused ones.
// It is in result.needsReview, where nothing is safe to ship.

The third bucket is the whole mechanism. An obligation in needsReview has not been decided either way; it is a question that has been raised and left open, and it stays visible until somebody closes it. Compare that with what a two-state input produces for the same system: a result where Article 50(1) simply is not there, indistinguishable from a system that genuinely does not interact with anyone.

The same discipline applies to a question that was never routed to the assessment at all. An input left out entirely decides the same way a false does, and we are not going to block a release because somebody did not enumerate every field in the schema, but it is written into the record as "not stated". false is a claim: someone looked and said no. "not stated" is the absence of a claim. They produce the same decision today and they are not the same thing in six months, when the question is why the duty was not applied and the honest answer is that nobody was asked.

This is also why we separated "unknown" from omission instead of collapsing them. "unknown" is an assertion of ignorance by someone who was asked, and it is strong enough to stop a release. Omission is silence, and silence does not get a veto, it gets a footnote in the record.

The gate belongs in CI, not in a meeting

assess() is a pure function over a plain object. No network, no clock, no reads from disk. Which means the open-question check is just a test, and it runs on every commit rather than at a review meeting a week before launch.

import { assess } from "disclosurekit";
import { profile } from "../src/ai-profile";

test("no open transparency questions", () => {
  const { needsReview } = assess(profile);
  expect(needsReview).toEqual([]);
});

That test fails the day an engineer adds image generation to an endpoint and marks the new input "unknown" because they do not know whether the output counts as a deep fake. The failure is correct and it is cheap to clear: either someone answers the question, or the team knowingly accepts an open item and records that it is open. What the test will not let you do is pass by saying nothing.

Keeping the profile in the repository next to the code it describes matters as much as the check does. A compliance answer that lives in a document drifts from the system within one sprint. An answer that lives in a typed object, read by a test, breaks the build when it stops matching reality, assuming someone updates the object, which is exactly the habit you are trying to install.

What the library refuses to tell you

The tri-state input has a sibling rule on the output side: the package reports what saying something does not cover.

import { requirements } from "disclosurekit";

requirements({ role: "deployer", emotionRecognition: true });
// [{ measure: "inform-exposed-persons",
//    obligations: ["art50-3"],
//    elements: [{ id: "ai-system", must: "…" },
//               { id: "biometric-operation", must: "…" }] }]

Some duties are discharged by wording and some are not. Article 50(2) asks for a machine-readable mark embedded in the content; telling a user in a sentence that an image was generated by AI is not that mark, and a run with no marker configured says so plainly rather than reporting success. A library that returned "compliant" there would be worse than no library, in the same way a checklist that reads blanks as noes is worse than no checklist: both hand you a result with the uncertainty removed.

The package also ships no sentences. It knows which elements a notice must get across and when and where it has to appear; it does not know your product's voice or your users' language, so the wording is yours, and a notice with an element left blank is refused.

import { withDisclosure, EvidenceLog } from "disclosurekit";

const log = new EvidenceLog();

export default withDisclosure(
  handler,
  { role: "provider", interactsWithPeople: true },
  {
    locale: "en-GB",
    text: { "ai-system": "You are chatting with our AI assistant." },
    log,
  },
);

The log is the other half of the three-state argument. An assessment and a disclosure that was actually shown both go into it as entries in a hash chain that verifies, and the log can be stamped with the ruleset version that was current when the decision was taken (new EvidenceLog({ rules: "eu-ai-act-article-50@0" })) so a decision made under an older reading is recorded as what it was rather than silently re-litigated.

What it costs to run

Almost nothing in machine terms. The assessment is a table lookup over a small object; it runs in a unit test, in a CI job, or in a request handler without anyone noticing. The middleware is built on the Web Request and Response, adds a header to every response, and touches the body only if you name a key for it, because a response body belongs to the service.

The real cost is social, and that is where the value sits. A needsReview entry is a work item with an owner, and somebody has to go and find out whether the vendor arrangement makes us a provider or a deployer. A two-state checklist spares you that conversation by answering on your behalf. The three-state version makes the open question visible, holds the release until it is closed, and leaves a record of which answers were given and which were never asked for.

None of this is legal advice, and the package says so in its own README. It is a map of the structure of one article, written by engineers, and where the answer matters a lawyer decides it. What the code can do is make sure the question reaches that lawyer instead of being closed by an empty box.

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

Withdrawing consent should be the same call as granting it

Shipmind Labs — Thu, 01 Oct 2026 13:22:05 +0000

The GDPR asks that consent be as easy to withdraw as it is to give. That reads as a requirement about buttons, and it is one, but it lands on the API underneath first: if refusing takes a different function, an extra argument or a confirmation step that granting does not need, the symmetry is gone before anything is rendered, and no amount of button styling brings it back.

We build compliance tooling for payment platforms and cross-border commerce, and consent is one of the places where the legal text and the code sit unusually close together. "As easy to withdraw as to give" is a statement about two code paths having the same shape. In most codebases they do not. Granting is a rich call that takes what was chosen and the context it was chosen in. Withdrawing is a thin one: a cleared storage key, a boolean flipped back, sometimes a dialog asking whether the visitor is sure. Those two calls are not inverses of each other, and everything downstream inherits the difference.

Our consent library, consentcore (https://github.com/shipmindlabs/consentcore), is built on the opposite rule: refusing is the same call as granting, the same parameters in the same order, the same return value, and the same kind of entry in the log.

Asymmetry is a property of the signature

Here is the pair a codebase usually ends up with. The names vary; the shape does not.

// not ours — the shape we keep finding
setConsent(["statistics", "marketing"], { noticeVersion: "2026-08" });
clearConsent();

The grant takes what was chosen and the context it was chosen in. The withdrawal takes nothing. Three consequences follow, and not one of them is a UI problem.

The withdrawal cannot be specific. A visitor who wants to keep analytics and drop advertising has no call to make, because the only refusal the API offers is all of it. The interface then grows a second, different path for partial changes, usually "open preferences and submit the whole set again", which is precisely the extra step the symmetry requirement is about.

The withdrawal has nothing to record against. It receives no notice version, no clock, no indication of how the decision was made, so it either writes a poorer record than the grant wrote or writes nothing at all.

And the withdrawal is implemented as deletion. clearConsent() clears the stored value, and the evidence that the visitor withdrew goes with it, the one event you are most likely to be asked to account for later.

The symmetric version puts the two directions on the same signature:

grant(["statistics"], options, state);   // adds statistics to what was already granted
refuse(["statistics"], options, state);  // removes statistics, leaves the rest alone

Same arguments, same order, same State back, same entry appended to the log. A grant adds to what was already granted; a refusal takes away what it names. Nothing on the refusal path is thinner, later, or more ceremonious than the grant path, because they are the same path with a direction.

One category does not move. necessary covers what the service cannot work without, and it survives being named in a refusal, not as a validation error the caller has to handle, just as a category that does not come off. That is structural rather than a rule someone has to remember:

export type Category = "necessary" | "preferences" | "statistics" | "marketing";

export const OPTIONAL_CATEGORIES: readonly Category[] = [
  "preferences",
  "statistics",
  "marketing",
] as const;

export const CATEGORIES: readonly Category[] = ["necessary", ...OPTIONAL_CATEGORIES] as const;

The whole-answer entry points keep the same discipline. acceptAll(options, previous),rejectAll(options, previous),accept(categories, options, previous) and withdraw(options, previous) all take the same options and the same previous state, and all return the same State. "Reject all" is not a special case implemented somewhere else; it is the same constructor with ["necessary"].

The record is the same record

A decision is a four-field object, and a refusal fills all four exactly as a grant does:

export type Decision = {
  readonly granted: readonly Category[];
  readonly at: string;
  readonly noticeVersion: string;
  readonly noticeHash: string;
  readonly method: "accept-all" | "reject-all" | "custom" | "withdrawn";
};

method is the field an audit actually asks about: not only what was granted but how the answer was arrived at. "withdrawn" sits in that union next to "accept-all", which is the whole reason the union exists. A withdrawal is a decision, not the absence of one.

const state = withdraw(options, previous);

state.decision.method;   // "withdrawn"
state.decision.granted;  // ["necessary"]
state.pending;           // true — the notice goes back on screen

That pending flag is the other half of symmetry. Withdrawing must not leave the visitor with no way to change their mind again, so the notice returns rather than the site quietly entering a state with no controls in it.

The log is append-only. A new decision supersedes the previous answer and never edits or drops it, because the superseded entry is the part that makes the record demonstrable. Storage written by an older version may hand back a single decision rather than an array, so restoring normalises both shapes:

export function asLog(stored: StoredConsent): readonly Decision[] {
  if (!stored) return [];
  return "method" in stored ? [stored] : [...stored];
}

And a withdrawal restored from storage does not read as "never asked": restore returns the withdrawn decision with pending: true, so the banner can come back while the record of why it came back is still sitting there.

Symmetry has to survive the side effects

A symmetric API is worth nothing if only one direction reaches the page. This is where the asymmetry usually reappears: granting starts things, and refusing merely stops new ones from starting.

One-shot work is gated, and work whose category is withdrawn is dropped rather than parked:

const gate = new Gate(state);

gate.when("necessary",  "session",   () => startSession());
gate.when("statistics", "analytics", () => loadAnalytics());
gate.when("marketing",  "pixel",     () => loadPixel());

gate.update(accept(["statistics"], options));

Necessary work runs immediately and synchronously so callers can rely on ordering, nothing runs twice however many decisions arrive, and a withdrawn category's pending work is discarded. Holding it in case the visitor changes their mind is how a queue becomes a loophole.

Third-party tags are different in kind. Queued work is a side effect that happens once and is over; a tag keeps running, and consent can move under it after it started. So tags are a registry, and a refusal removes them:

const tags = new Tags(state);

tags.register({ id: "analytics", purpose: "statistics", src: "https://cdn.example/a.js" });
tags.register({
  id: "pixel",
  purpose: "marketing",
  src: "https://cdn.example/p.js",
  cleanup: () => { document.cookie = "_pxl=; Max-Age=0"; },
});

tags.update(accept(["statistics"], options));  // analytics goes on the page, the pixel does not
tags.update(withdraw(options, state));         // the analytics element comes off it

Removed, not neutralised, not left in place with type="text/plain" waiting to be revived, which keeps a refused vendor one line of unrelated code away from running. cleanup is where the cookie the tag already set gets dealt with, because taking an element off the page does not undo what it did while it was there. Elements carry data-consent-tag and data-consent-purpose, so you can inspect a page for what is running and under which answer, and tags.history is the record of both directions. A later grant releases a removed tag again: a new answer to the same question, not a replay of the old one.

A refusal can only be as specific as the answer

Categories are a coarse answer. "statistics" does not say which vendor gets the request or what they set, and the list that does say it is usually prose written three times, in the banner, in the cookie policy, and in a record of processing, which then drift apart. Declaring it once as data fixes both the drift and the granularity question:

const declaration = declare({
  purposes: [
    { id: "audience", category: "statistics", name: "Counting visits",
      description: "Which pages are read, in aggregate." },
    { id: "retargeting", category: "marketing", name: "Advertising",
      description: "Showing you ads for this site on other sites." },
  ],
  vendors: [
    { id: "acme-analytics", name: "Acme Analytics", purposes: ["audience"],
      policy: "https://acme.example/privacy", cookies: ["_acme"], transfers: "US" },
    { id: "adnet", name: "AdNet", purposes: ["audience", "retargeting"] },
  ],
});

allowsPurpose(declaration, state, "audience");   // true
allowsVendor(declaration, state, "adnet");       // false: retargeting was not granted
runnable(declaration, state);                    // ["acme-analytics"]

A purpose is answered through its category, so two purposes under one category are one answer, and therefore one refusal. If you want them refusable separately, that is a decision about the declaration, not about the banner. declare checks the declaration rather than trusting it: a vendor may only name purposes that exist, an id may only be used once, and a purpose with no description is refused, because a notice made of identifiers informs nobody. What comes back is plain data, so you can commit it next to the code, diff it in review, and publish it beside the notice.

What it costs to run

An append-only log grows, and it is stored per visitor. It is small, four fields per decision, but it is not free, and the restore path has to tolerate both the old single-decision shape and the array.

Binding a decision to a fingerprint of the notice text means editing the wording re-asks everyone, whether or not the version string was bumped. That is the intended behaviour, and it makes notice edits a deliberate act with a cost attached rather than a copy change.

Dropped queued work is not resurrected by a later grant, while removed tags are released again. That difference is a design decision you have to make per side effect: if something must come back when consent returns, it belongs in the registry, not the gate.

And cleanup is real work. Every vendor that sets something needs a function that unsets it, written by someone who knows what it set. There is no generic version of that.

Close

Symmetry is cheap when it is in the signature from the beginning and expensive to retrofit, because by then the refusal path has grown its own storage behaviour, its own record format, and its own set of side effects that only run in one direction. The test is not what the banner looks like. It is whether you can write the refusal as the same call as the grant, hand it the same arguments, and get back the same kind of state and the same kind of log entry. If you cannot, the property the regulation asks for is probably not in the product, wherever the buttons ended up.

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

Split five cents three ways: allocation that sums back exactly

Shipmind Labs — Wed, 30 Sep 2026 13:21:52 +0000

Totals drift at the point where an amount is divided. Five cents split three ways cannot be three equal amounts, and a payout split pro rata across investors almost never lands on whole minor units, so every division leaves a remainder that has to go somewhere specific. Code that computes each share on its own and trusts the parts to add back up is the most common way a ledger ends up a cent away from itself, in a place nobody can attribute.

We build payment services, multi-investor payout flows, and the reconciliation that sits behind them, and the same defect keeps arriving in the same shape. Not a wrong total. A total that was right until it was split.

The naive split fails in both directions

Work in minor units and integer division quietly drops the remainder:

const total = 5n;        // five cents
const each = total / 3n; // 1n
each + each + each;      // 3n - two cents have disappeared

Work in floats and the opposite happens. 0.05 / 3 is 0.016666...; round each share to two decimals and you get three amounts of 0.02, summing to 0.06. A cent has been invented.

The two failures are not equally annoying. A missing cent tends to surface as a support ticket from whoever received the short share. An invented cent surfaces as a reconciliation break, because the distribution no longer matches the amount that was actually settled, and that one is found by accountants rather than by monitoring.

Both come from the same mistake: treating each share as an independent rounding problem. It isn't. The shares are a partition of a known total, and the total is the invariant.

Allocation is a function of the total, not of the shares

The fix is the largest-remainder method, applied in minor units. Compute every share by flooring, count how many units are left over, and hand those units out one each to the parts with the largest remainders. The parts then sum back to the original exactly, by construction rather than by luck.

That is what allocate() does in our money-input library, amountfield. The library exists for the input side, a React field that never holds a float and never assumes a currency has two decimals, but the arithmetic underneath it is the part that gets reused in ledger code, and this is the rule it implements:

const floorDiv = (a: bigint, b: bigint): bigint => {
  const q = a / b;
  return a % b !== 0n && a < 0n !== b < 0n ? q - 1n : q;
};

function largestRemainder(total: bigint, weights: readonly bigint[]): bigint[] {
  const sum = weights.reduce((acc, w) => acc + w, 0n);
  const shares = weights.map((w) => floorDiv(total * w, sum));
  const remainders = weights.map((w, i) => total * w - shares[i] * sum);

  let leftover = total - shares.reduce((acc, s) => acc + s, 0n);
  const order = remainders
    .map((r, i) => [r, i] as const)
    .sort((a, b) => (b[0] === a[0] ? a[1] - b[1] : b[0] > a[0] ? 1 : -1));

  for (const [, i] of order) {
    if (leftover === 0n) break;
    shares[i] += 1n;
    leftover -= 1n;
  }
  return shares;
}

Two details in there are load-bearing, and both are easy to get wrong.

The first is floorDiv. JavaScript's bigint division truncates toward zero, not down. For positive totals the two agree; for negative ones they don't, and the difference is the whole correctness argument. With flooring, every remainder is non-negative and the leftover count stays between zero and the number of parts, so the distribution loop is the same code for a charge and for a refund. With truncation you get a negative leftover for negative totals and need a second branch, which is exactly the branch that goes untested.

The second is the tie-break. When two parts have the same remainder, the lower index wins. That looks like a detail until a reconciliation job is re-run and produces a different split than the one already booked. A split has to be a pure function of the total and the weights, in that order, with no dependence on iteration order of a map or on the order rows came back from the database.

Weights, negatives, and the one-unit rule

Equal parts are the easy case. Real allocation carries weights: pro-rata returns across investors in a loan, a fee split between a platform and a merchant, a document-level discount spread across order lines.

total	weights	shares	sum
5	1, 1, 1	2, 2, 1	5
5	3, 7	2, 3	5
-5	1, 1, 1	-1, -2, -2	-5

For equal weights there is a property worth asserting in a test: no two shares differ by more than one minor unit. It is the closest thing to fairness that integer arithmetic can offer, and it fails loudly if someone later replaces the allocation with per-share rounding.

The negative row deserves a second look. The leftover units get added, so for a negative total the first parties end up with the smaller magnitude rather than the larger one. That is internally consistent, but it means a refund allocated on its own is not necessarily the mirror image of the charge it reverses. If your domain requires a partial refund to walk back the original split exactly, allocate the positive amount and negate the result, or allocate against the amounts already booked. Whichever you choose, choose it, because this is not a case where the library can guess.

The same goes for the extra cent itself. Largest remainders is a defensible, deterministic default, and it is the right one when the parties are peers. It is the wrong one when the rule is "the platform absorbs the remainder" or "the remainder follows the largest position, not the largest fractional part". Those are business rules, and they belong at the call site as an explicit step on top of an exact allocation, not as an emergent property of whichever iteration happened to run last.

Multiplication is where a rounding mode hides

Division is the obvious place a total drifts. Multiplication is the quiet one, because it looks like it has a right answer.

multiply(price, 0.1);     // refused: the JavaScript number 0.1 is not one tenth
multiply(price, "0.1");   // refused: no rounding mode given

The first refusal is the float problem wearing a different hat. 0.1 as a double is not one tenth, and a ratio that is already wrong before the multiplication cannot be rescued by rounding after it. So multiply() takes the ratio as text, as a bigint, as a whole number, or as a numerator and a denominator, every form that can express the intended ratio exactly, and rejects the one form that cannot.

The second refusal is the interesting one. A fee of 2.9% of some amount is generally not a whole number of minor units. Half-up, half-even, and toward-zero all produce defensible answers, they differ by a unit, and the difference compounds across a settlement run. Picking one silently means the library has made a policy decision on behalf of a caller who never knew a decision was being made. So multiply() throws when no rounding mode is given. The error arrives in the first test run rather than in a month-end report.

add() behaves the same way about currencies: it refuses to mix them rather than adding the numbers and keeping the first currency code. It is the same principle three times over, that a wrong amount is worse than an error, and it is the same principle that makes the input field refuse an unknown currency code instead of assuming two decimals, or refuse a pasted $12.34 in a EUR field instead of reading it as euros.

What it costs to run

Very little at runtime. Everything is bigint arithmetic over minor units, allocation is one pass plus a sort over the number of parts, and no value ever becomes a Number on the way through, since even formatting goes through a decimal string rather than a float.

The real cost is argument surface. Callers have to supply weights, name a rounding mode, and carry a currency with its exponent, and none of those can be defaulted honestly. That is the trade: a handful of required arguments in exchange for arithmetic that cannot silently invent or lose a unit.

One thing you get for free by staying in minor units is the currency exponent. Allocation hands out the currency's own smallest unit, so splitting a JPY amount distributes whole yen and splitting a KWD amount distributes thousandths, without a special case anywhere in the allocation code. The exponent comes from the bundled ISO 4217 table, and a code the table does not carry is refused rather than assumed, which is probably why multiply() and allocate() can be exact: they never have to guess how small a unit is.

Close

Every split of an amount contains a decision about who gets the extra unit. The decision is unavoidable, and the only real choice is whether it is written down or left to the shape of a loop. Allocate from the total in minor units, floor the shares, hand the leftovers to the largest remainders, keep the tie-break deterministic, and make multiplication ask for its rounding mode. The parts then add back to the whole every time, and the cent that someone has to receive is the cent you decided to give them.

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

A credit note is a type code, not a minus sign

Shipmind Labs — Tue, 29 Sep 2026 13:29:36 +0000

A refund issued as an invoice with negative amounts puts the direction of the money in the sign of every figure on the document, instead of in the one field a receiver is required to read. EN 16931 puts direction in the type code, BT-3, and gives the refund its own document type. When the sign and the code disagree, the same money can get booked twice, once from the original invoice, and once more by a system that reads a negative invoice as another payable rather than as a reversal.

We build payment and invoicing services, and this is the defect that survives every other fix. The totals reconcile. The VAT breakdown is consistent with the lines. The document is still wrong, because the fact that makes it a refund was never stated, only implied, by arithmetic, across a dozen elements. Our EN 16931 validator, invoicerules, treats that as a rule violation rather than a stylistic preference.

The type code decides which document it is

In UBL a credit note is not an invoice with a flag set on it. It is a different root element, a different line element, and a different quantity element. In invoicerules that decision is one predicate over one field:

import { isCreditNote } from "invoicerules";

isCreditNote({ typeCode: "381" }); // true
isCreditNote({ typeCode: "261" }); // true
isCreditNote({ typeCode: "380" }); // false
isCreditNote({ typeCode: "" });    // false

The codes are UNCL1001's, the code list BT-3 draws on; 380 is an invoice, 381 a credit note. toUBL asks this question once, at the top, and then writes a different tree. The test that pins it down reads like the difference itself:

const xml = toUBL(creditNote());

assert.ok(
  xml.includes(`<CreditNote xmlns="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2"`),
);
assert.ok(xml.includes("<cbc:CreditNoteTypeCode>381</cbc:CreditNoteTypeCode>"));
assert.ok(xml.includes(`<cbc:CreditedQuantity unitCode="C62">2</cbc:CreditedQuantity>`));
assert.ok(xml.includes("<cac:CreditNoteLine>"));
for (const invoiceOnly of ["<cac:InvoiceLine>", "InvoicedQuantity", "InvoiceTypeCode"]) {
  assert.ok(!xml.includes(invoiceOnly), `the credit note carries ${invoiceOnly}`);
}

// The parties, the breakdown and the totals are the same elements as always.
assert.ok(xml.includes("<cbc:CompanyID>PL5260250274</cbc:CompanyID>"));
assert.ok(xml.includes(`<cbc:PayableAmount currencyID="EUR">246.00</cbc:PayableAmount>`));
assert.ok(!/>-\d/.test(xml), "an amount was written with a minus sign");

Three element names change, plus the root. The parties, the VAT breakdown and the monetary totals are written by exactly the code that writes them on an invoice. That is what makes this cheap to implement correctly: a credit note is a different document, not a different mapping, so there is no second mapping to keep in sync with the first.

The last assertion is the one this article is about. No amount anywhere in the output carries a minus sign, not on a line, not in a tax subtotal, not in the totals block.

A negative invoice is the same money twice

Consider what a receiver has to do with a document whose type code says 380 and whose amounts are all negative. There are two consistent implementations, and both are defensible.

One reads BT-3, sees an invoice, and books a payable. The amounts are negative, so the payable is negative, and if nothing downstream is prepared for a negative payable it becomes a zero, an absolute value, or an exception in a ledger that nobody watches in real time. The other ignores the type code, notices the signs, and treats the document as a reversal of something, but it has to guess what, because a sign is not a reference.

The original invoice has already been booked. Now the refund is booked again, or booked twice, or not at all, depending on which of those two receivers is on the other end. The failure is not that either implementation is wrong; it is that the document did not say which one is correct. Direction was left to be derived, and derivation is where two correct systems disagree.

The type code removes the derivation. It is one field, on one document, in a closed code list, and every receiver reads it in the same place. Amounts then have one job, magnitude, and the sign stops carrying meaning it was never defined to carry.

This matters more under a clearance model than it did when an invoice was an email. A document that fails validation at the platform was never issued; there is nothing to correct, because nothing exists. Failing at our own desk, with a message naming the rule, is better than failing at theirs.

Refusing it before the platform does

So invoicerules refuses it. A document with an invoice type code and negative amounts fails, and the failure names every element where the sign appears:

const result = validate(negative);
result.ok; // false

result.violations
  .filter((v) => v.rule === "INVOICERULES-CN-01")
  .map((v) => v.path);
// [
//   "/Invoice/InvoiceLine[1]/LineExtensionAmount",
//   "/Invoice/TaxTotal/TaxSubtotal[1]/TaxableAmount",
//   "/Invoice/LegalMonetaryTotal/LineExtensionAmount",
//   "/Invoice/LegalMonetaryTotal/TaxExclusiveAmount",
//   "/Invoice/LegalMonetaryTotal/TaxInclusiveAmount",
// ]

The message on the first of those says a refund is a credit note, type code 381. Alongside it, BR-27 fires on the negative item net price, because that one is the standard's rule and always was.

Two details about that identifier are deliberate. It is prefixed INVOICERULES- because it is not EN 16931's. Every other rule in the library carries the standard's own identifier, or Peppol's where the standard leaves an arithmetic rule to the syntax binding, precisely so that an error from us and an error from the receiving end name the same thing. A rule of our own must not be mistakable for one a receiver will quote back. And it is reported against each element rather than against the document, because a violation is a place. "This invoice has negative amounts" is a sentence someone has to go and investigate; five paths are five edits.

Flipping the type code to 381 without fixing the amounts does not satisfy the rule either:

const result = validate({ ...negative, typeCode: "381" });
const violation = result.violations.find((v) => v.rule === "INVOICERULES-CN-01")!;
violation.message; // a credit note states what it credits as a positive amount ...
violation.path;    // "/CreditNote/CreditNoteLine[1]/LineExtensionAmount"

A credit note already means "this is money going back". Stating it again with a minus sign either double-negates or does nothing, and which of the two is another derivation we would be asking a receiver to perform. Allowances behave the same way: a negative allowance amount is refused under BR-31, at /CreditNote/AllowanceCharge[1]/Amount, because an allowance already has a direction in its name.

One rule set, two trees

The paths above are worth looking at twice. The same rules run against both document types, and they report against the credit note's own elements:

const result = validate(creditNote());
result.ok; // true
result.coverage.every((entry) => entry.path?.startsWith("/CreditNote")); // true

const wrong = validate(creditNote({ lines: [line("100.00", "250.00")] }));
wrong.violations.find((v) => v.rule === "PEPPOL-EN16931-R120")!.path;
// "/CreditNote/CreditNoteLine[1]/LineExtensionAmount"

A line net amount that does not match price times quantity is the same defect on both documents, checked by the same rule, and quoted back at the path it has in the document that actually gets sent. This is the other half of not duplicating the mapping: we do not maintain a credit-note rule set either. The rules are written against the model; only the path builder knows which tree it is in.

Where a minus sign is still correct

The rule is not "no negative numbers anywhere". BT-115, the amount due for payment, may be negative, because more can have been prepaid than was owed. That is a balance, not a direction. It is the result of arithmetic the document itself states, and the receiver does not have to infer anything from its sign.

One more asymmetry is worth knowing before it surprises someone: a credit note has no due date element at all.

const xml = toUBL(creditNote({ dueDate: "2026-09-20", paymentTerms: "Credited to the account" }));
xml.includes("<cbc:DueDate>");                                // false
xml.includes("<cbc:Note>Credited to the account</cbc:Note>"); // true

UBL carries BT-9 on an invoice only. If there is something to say about when and how the money goes back, the payment terms are the place to say it, and the model lets the field through so that callers with one shared document builder do not have to branch. The writer simply does not emit it.

What it costs to run

Almost nothing, which is the argument for doing it at the boundary rather than in a reconciliation job later. One predicate over one field, one path builder that knows which root it is under, one rule set. The recurring cost is in the tests, and specifically in the assertions about absence: that no invoice-only element name appears in a credit note, and that no amount anywhere carries a minus sign. Those are the assertions that catch a regression the day someone adds an element to the writer and forgets there are two documents.

The habit underneath is probably the same one that keeps money out of floats: do not encode a fact in something that also means something else. Sign means magnitude direction in arithmetic; it does not mean document direction in a tax document, no matter how clear it looks on screen. Put the fact in the field the standard reserved for it, and refuse the document that does not.

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

A deep link routing table is an authorisation boundary

Shipmind Labs — Wed, 23 Sep 2026 13:27:19 +0000

A deep link is a URL that anyone can send you. It arrives from an email, a text message, another app, or a QR code on a poster, and it picks a screen in an app that may already be signed in. The code that decides which screen is usually a chain of startsWith checks plus a params object holding whatever came after the last slash, a switch statement standing where an authorisation boundary belongs.

We build mobile apps alongside the backends they talk to, often role-specific apps for couriers, warehouse staff and operations teams, and notification services that fan out to push, WhatsApp and Telegram. Every one of those messages carries a link back into the app. That link is the least trusted input the app receives, and it is the input we have repeatedly seen handled with the least ceremony. We wrote our thinking down as a library, deeplinkmap, because the argument is easier to make in types than in prose.

What the chain of startsWith checks actually decides

Four things go wrong, and they go wrong together.

Parameters are strings from a stranger, passed straight into a screen that expects an id, so /order/DROP TABLE reaches the query builder. The fallback is "open whatever we matched last", so a link that matches nothing lands somewhere arbitrary, often on a screen nobody meant to expose. A link that arrives while nobody is signed in is opened anyway, and the screen fails oddly instead of the app asking for a login and resuming afterwards. And every link counts as equally trustworthy, although a universal link is one the operating system checked against a host that serves apple-app-site-association or assetlinks.json naming this app, while a custom scheme is a namespace any installed app can also register and any web page can link to.

None of these is a bug in the sense of a wrong line. They are the defaults you get when routing is written as dispatch rather than as a decision about what a stranger is allowed to ask for.

Declare the placeholder, or the table does not build

The first rule we hold to is that a placeholder says what it may contain, in the table, before anything runs.

export type ParamKind = "string" | "number" | "uuid" | "slug";

export type ParamSpec = {
  readonly kind: ParamKind;
  /** Refuse anything shorter. Defaults to one character. */
  readonly minLength?: number;
  /** Refuse anything longer. Defaults to 128 characters. */
  readonly maxLength?: number;
  /** Closed range for a "number". Refused on any other kind. */
  readonly min?: number;
  readonly max?: number;
  /** The complete set of accepted values. Anything else is refused. */
  readonly oneOf?: readonly (string | number)[];
};

A kind says what a value looks like; a constraint says which of those values the screen actually has. :id declared as number reaches the screen as a number, already inside its range, and /order/1 OR 1=1 never gets that far.

The part that matters more than the validation is what happens when a route forgets to declare something. A route with a placeholder in its pattern and no declaration for it fails at construction. It throws InvalidRoute, because an undeclared placeholder would otherwise arrive as an unvalidated string from a stranger. Same for a pattern that repeats :id twice, a route name declared twice, a min above its max, a min on a slug, or a oneOf value that its own kind rejects. A table that cannot mean what it says refuses to exist rather than sending links quietly nowhere in the field.

This is the trade we like: the failure moves from a user's phone, months later, to a failing test or a failed boot on the machine of whoever edited the table.

const router = new Router(
  [
    {
      name: "order",
      pattern: "/order/:id",
      params: { id: { kind: "number", min: 1 } },
      requiresAuth: true,
    },
    {
      name: "article",
      pattern: "/article/:slug",
      params: { slug: "slug" },
      query: { ref: "slug" },
      accepts: ["universal", "scheme"],
    },
    // No accepts: a reset token only arrives through a verified link.
    { name: "reset", pattern: "/reset/:token", params: { token: "uuid" } },
  ],
  { schemes: ["myapp"], hosts: ["example.com", "*.example.com"] },
);

Read that table as a policy document and it answers questions a reviewer can hold in their head: which screens a stranger can address, what shape the arguments take, which of them need a session first.

The door a link came through is part of what it may do

The two doors are not equally trustworthy, so accepts is declared per route: universal, scheme, or both, defaulting to universal links only. The article route above opens to both, because the worst outcome of a forged article link is that somebody reads an article. The reset route says nothing, so it inherits the default and declines the unverified door entirely. A token that can change an account should not arrive through a namespace any installed app can register.

Hosts are compared whole. example.com matches example.com, and *.example.com matches exactly one label below it. example.com.evil.net ends with the declared host and is somebody else's site, which is exactly what a startsWith or endsWith check lets in, and following it is how an app becomes an open redirect wearing native UI. http belongs to a separate switch, allowInsecure, off by default and meant for local development. An allow-list that cannot mean what it says (*, *.com, a URL where a hostname belongs, a route open to no door at all) throws InvalidPolicy when the router is built.

A refusal is a value, not a missing else-branch

Resolving a link returns one of two things, and the second one is as much a part of the API as the first.

export type Refusal = {
  readonly reason:
    | "unparseable"
    | "insecure-scheme"
    | "foreign-host"
    | "unknown-scheme"
    | "form-not-accepted"
    | "no-route"
    | "bad-parameter";
  readonly detail: string;
  readonly url: string;
};

export type Resolution<Name extends string = string> =
  | { readonly ok: true; readonly match: Match<Name> }
  | { readonly ok: false; readonly refusal: Refusal };

Seven named reasons, and no-route is one of them: a link that matches nothing goes nowhere, because "open whatever matched last" is how a stranger's link lands on a screen nobody meant to expose. A refusal comes back whole, so no screen is ever handed a half-filled parameter object built out of the placeholders that happened to validate before the one that did not. Query parameters are allow-listed on the same terms: declared ones are validated, everything else is dropped rather than passed on to a screen that might forward it somewhere.

The call site then reads as a short list of decisions rather than a funnel of guards:

function handle(delivery: Delivery | null) {
  if (delivery === null || delivery.status === "duplicate") return;
  if (delivery.status === "refused") return report(delivery.refusal);

  const { match } = delivery;
  if (match.requiresAuth && !session) {
    pending.hold(match);              // resume after signing in
    // ...send the user to sign in; the held match is replayed afterwards
  }
  // ...navigate
}

requiresAuth is answered by the table, not by each screen remembering to check, and the link that arrived too early is held as a validated match rather than as a raw URL replayed later through a code path nobody re-reads.

What it costs to run

Less than the version it replaces, which is unusual enough to say plainly. The table is built once at startup, and the per-link work is a path comparison plus a handful of anchored regular expressions. The module imports nothing from React Native, since Linking hands it a string, so the whole routing table is testable in a plain test runner, on a laptop, without a device or a simulator. That is where the cost lands: the routes have tests, and a policy change is a diff in one file rather than an audit of every screen.

The operational payoff is probably the refusal reason. foreign-host and unknown-scheme in the logs are not noise. They are somebody trying links against your app, and they are legible because each refusal carries its reason and the URL as received, for logging, not for routing.

The habit underneath all of this is the one we apply to payment callbacks, webhook receivers and signed-document links alike: anything that arrives from outside gets a declared shape, a boundary that refuses in named ways, and a build that fails when the declaration is missing. A deep link is not a smaller case of that. It is the same case, holding a screen.

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