DEV Community: KMJ Tire Calgary

What Did It Cost on March 3rd, and When Did We Know? Bitemporal Modeling for a Service Price Catalog

KMJ Tire Calgary — Wed, 19 Aug 2026 16:22:21 +0000

What Did It Cost on March 3rd, and When Did We Know? Bitemporal Modeling for a Service Price Catalog

Two Questions Wearing One Costume

Someone shows up at the counter in mid-March holding a printed quote from the previous week — the sort of figure anyone comparing prices around town collects before deciding. The number on the paper is not the number on the screen. Two explanations exist, and only two. Either the price genuinely changed between then and now, or the number on the paper was wrong when it was printed and has since been corrected. Those are different situations with different remedies, and the person standing there deserves to know which one they are in.

A schema with a single updated_at column cannot tell them. It cannot tell you either. updated_at records that a row was touched. It says nothing about the period during which the value it holds was the truth, and once it has been overwritten it says nothing about what the value used to be. You have thrown away both axes and kept a timestamp that answers neither question.

Here are the two questions, stated precisely, because the whole design falls out of taking them literally:

What was the price on March 3rd? This is a question about the world. It has an answer independent of what any database contained.
What did our system say the price on March 3rd was, as of March 10th? This is a question about our beliefs. It has a different answer, and on the day of a dispute it is usually the more useful one.

The first axis is called valid time: the period during which a fact was true of reality. The second is transaction time: the period during which our system asserted that fact. Model both and every version of the question above becomes a SELECT. Model one, and you are guessing. Model neither, and you are reconstructing history from Slack messages.

Framing: What Follows Is a Design Exercise

I work with a Calgary tire and oil-change business, a local independent operation with the ordinary pressures of that trade: a violent twice-yearly changeover rush, seasonal price movement, quotes issued days before the work happens, and fleet customers who reconcile invoices at month-end against numbers they were given weeks earlier. Those constraints are real and they are why this modeling problem is interesting to me.

The system described below is a design exercise. It is how I would model a service and price catalogue for a business shaped like that one. There is no deployment behind it, no incident report, no migration, no rollout, no measured adoption. Nothing here is running production infrastructure. The SQL is written against PostgreSQL 14-and-later semantics — multiranges, range_agg, INCLUDE columns on partial indexes — and it is a design sketch to adapt and test in your own instance, not a migration to paste. The scenario around it is a scenario, not a log.

Every dollar figure in this article is illustrative. I picked round numbers that make the interval arithmetic legible on a page. They are not anyone's prices, they are not derived from anyone's prices, and you should not read them as such. The engineering claims are checkable and I checked them. The money is pedagogy.

Valid Time and Transaction Time, Without Hand-Waving

Valid time is a property of the fact. "Mounting and balancing a 17-inch wheel is $45" was true from the first of October until the first of March. That statement is about the world. It remains true whether or not anybody ever wrote it down, and it stays true after the database is dropped.

Transaction time is a property of the record. "Our catalogue asserted that mounting a 17-inch wheel is $45" was true from 14:22 on September 28th until 09:05 on November 2nd, when someone replaced the row. That statement is about us. It is not falsifiable by the world — either we asserted it or we did not — and it is the only axis that gives you an audit trail.

The two come apart constantly, and the gap between them is where all the interesting behaviour lives:

Future-dated change. On September 28th we record that from October 1st the seasonal changeover rate goes up. Valid time starts after transaction time. For three days the system holds a fact about a future it has not reached.
Backdated correction. On March 12th we learn the figure we published on March 1st was wrong. Valid time starts before transaction time. For eleven days we asserted something false, and — this is the part that matters — we need to keep asserting that we asserted it.
Retroactive restatement by a third party. A supplier says a line was mispriced from the first. We did not err; we were fed bad input. Valid time again precedes transaction time, but the story and the remedy both differ.

Any one of these is expressible with a single axis if you squint. All three together are not. The moment you need "what did we believe last Tuesday about last Monday," one axis is provably insufficient — you are asking for a value indexed by two independent coordinates.

Soft Deletes and a Touched-At Column Are Not Version History

The standard evolution of a price table goes like this, and I have watched it happen more than once.

Version one is price with an updated_at. Someone asks what a rate was last month. Nobody can answer.

Version two adds price_history, populated by a trigger. That answers "what did the row look like before the last edit," which is a different question. History tables record edits, not periods. Three edits in one afternoon, two of them typos, produce three rows and no way to tell which two were wrong.

Version three adds effective_date. This is real progress — it is a valid-time lower bound — but there is no upper bound, so "which row applies on March 3rd" becomes ORDER BY effective_date DESC LIMIT 1 with a <= predicate, and that query is a lie the moment somebody inserts a correction with an effective_date in the past. The correction silently changes the answer to historical questions, with no record that the answer used to be different.

Version four adds deleted_at and calls it versioning. It is not. A soft delete is a tombstone with a timestamp; it tells you a row stopped being used, not when the fact stopped being true, and not what replaced it. Two rows both soft-deleted five minutes apart give you no ordering of beliefs, only an ordering of clicks.

The tell that you are in this hole is a support conversation containing the phrase "let me check the audit log." If the audit log is a separate artifact from the data, the data has no history and you are reconstructing it from a side channel nobody tested. History is not a side channel. It is the table.

The Shape of the Table

Here is the core object. It is append-only in the sense that facts are never erased; the only in-place mutation permitted is closing a transaction-time upper bound, and I will argue later that even that should go through one function and nothing else.

CREATE EXTENSION IF NOT EXISTS btree_gist;

CREATE TYPE offering_state AS ENUM ('priced', 'not_offered', 'on_request');

CREATE TABLE service_price (
    row_id        bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    catalog_key   text          NOT NULL,
    state         offering_state NOT NULL DEFAULT 'priced',
    amount        numeric(10,2),
    currency      char(3)       NOT NULL DEFAULT 'CAD',
    valid_span    daterange     NOT NULL,
    txn_span      tstzrange     NOT NULL,
    authored_by   text          NOT NULL,
    intent        text          NOT NULL,
    note          text,
    CONSTRAINT amount_matches_state CHECK (
        (state = 'priced' AND amount IS NOT NULL)
        OR (state <> 'priced' AND amount IS NULL)
    ),
    CONSTRAINT valid_span_has_start CHECK (NOT lower_inf(valid_span)),
    CONSTRAINT txn_span_has_start   CHECK (NOT lower_inf(txn_span)),
    CONSTRAINT spans_nonempty       CHECK (NOT isempty(valid_span) AND NOT isempty(txn_span))
);

Five decisions in there are worth defending.

valid_span is a daterange, not a tstzrange. Prices in this domain change on business dates, not at 14:07:33. Using a date range removes an entire category of questions — what instant does "starting October 1st" mean, in which zone, and what about the row that starts at midnight — by making them unrepresentable. If you genuinely need intra-day valid time, use tstzrange and read the section on local dates below twice.

txn_span is a tstzrange because transaction time is an instant, always, and it is assigned by the system. Users may specify any valid time they like. Users may never specify transaction time. The moment you let an operator backdate the transaction axis, the audit property is gone and you have an expensive table with none of the benefits.

Catalogue keys deserve a word too. MOUNT_BALANCE:17 bundles two operations — mounting and wheel balancing — under one priced unit, keyed on a rim diameter that comes straight off the markings on the sidewall. Keys should be stable strings that never encode a price, a season, or a supplier, because anything encoded in the key cannot be corrected by the mechanism this whole article is about.

state exists so that absence never has to be interpreted. A missing row and a row saying "we do not price this" are different facts, and I will come back to why.

intent is free text with a house vocabulary — initial, scheduled, correction, supplier_restatement, withdrawal. Some of it is derivable from the two lower bounds, but derivation cannot separate "we typed it wrong" from "we were told wrong," and those land very differently on anyone quoted under the old figure.

Half-Open Intervals and the Tax Closed Ones Charge

Both spans are half-open: [lower, upper). Lower bound included, upper bound excluded. This is not a stylistic preference, it is the only convention that composes.

With half-open intervals, adjacency is equality: the span that ends on April 1st and the span that begins on April 1st are adjacent with no gap and no overlap, and you can test that with upper(a) = lower(b). With closed intervals you write the previous span as ending March 31st, and now adjacency requires you to know the granularity of the type in order to add one to it. That knowledge leaks everywhere. It leaks into application code, into reporting queries, into the CSV export, and into whatever service consumes the CSV export.

The failure mode is specific and I have seen its fingerprints in more than one schema: someone widens a column from date to timestamp, and every "minus one day" in the codebase is now wrong by 86,399 seconds. A hole opens in the history on every boundary day, and the daily revenue query does not error — it returns nothing for that key on that date, and the number is quietly a little low forever.

PostgreSQL helps on one axis and not the other, and the asymmetry catches people. The behaviour below is documented rather than surprising, which somehow makes it easier to be bitten by:

SELECT daterange('2026-03-01', '2026-03-31', '[]') AS canonicalized;
--  canonicalized
-- -------------------------
--  [2026-03-01,2026-04-01)

SELECT tstzrange('2026-04-01 00:00-06', '2026-05-01 00:00-06', '[]') AS untouched;
--  untouched
-- ----------------------------------------------------
--  ["2026-04-01 00:00:00-06","2026-05-01 00:00:00-06"]

daterange is a range over a discrete type, so Postgres canonicalizes every literal to [) regardless of what you wrote. tstzrange is continuous and cannot be canonicalized, so an inclusive upper bound survives — and two "adjacent" tstzranges written with [] will overlap at exactly one instant, which is precisely enough to make an exclusion constraint reject an insert that looks obviously fine to the person writing it. Construct every tstzrange with an explicit '[)' third argument. Every one. Make it a lint rule if you have to.

Unbounded upper bounds are the other half of the convention. A currently-believed row has txn_span with an infinite upper bound, written tstzrange(now(), NULL, '[)'), and a price with no scheduled end has valid_span unbounded above. upper_inf(txn_span) then becomes the definition of "this is a row we currently assert," which is a cheap and very indexable predicate.

Two Truths at One Instant Are a Bug, So Make Them Impossible

The invariant that makes the whole model trustworthy is this: for any catalogue key, any valid date, and any transaction instant, at most one row applies. Enforce it in the database, because enforcing it in the application means enforcing it in every code path anyone will ever add.

ALTER TABLE service_price
  ADD CONSTRAINT service_price_single_truth
  EXCLUDE USING gist (
      catalog_key WITH =,
      valid_span  WITH &&,
      txn_span    WITH &&
  );

Read what that actually forbids, because it is subtler than it looks. It rejects a pair of rows for the same key whose valid spans overlap and whose transaction spans overlap. Overlap on one axis alone is not merely permitted, it is the entire point:

A correction produces two rows with overlapping — often identical — valid spans. Their transaction spans are disjoint, because the old row's belief window was closed at the instant the new one opened. Allowed.
A scheduled price change produces two rows with overlapping transaction spans, both currently believed. Their valid spans are disjoint, one ending where the next begins. Allowed.
Two rows both claiming to be the truth for the same key on the same day at the same instant. Rejected, at the storage layer, with a constraint violation and a row identifier.

The catalog_key WITH = element requires btree_gist, which teaches GiST equality on scalar types. Without the extension the constraint will not build.

One caveat that bites during backfills: the constraint is checked immediately, row by row, as each insert lands. A multi-row rewrite that passes through an intermediate overlapping state fails even when the final state would have been clean. You can declare the constraint DEFERRABLE INITIALLY DEFERRED and push the check to commit, and occasionally that is the pragmatic answer, but I would rather not — a deferred check turns a precise error at the offending statement into a vague one at commit time, and it invites write paths that are only correct in aggregate. Order the writes instead: close before you open, inside one transaction. The intermediate state is then a gap rather than an overlap, which the constraint permits and which no other session observes, because nothing has committed.

The Query Nobody Argues About: Current Truth

Start with the boring one, because it establishes the shape.

SELECT sp.catalog_key,
       sp.state,
       sp.amount
  FROM service_price AS sp
 WHERE sp.catalog_key = 'MOUNT_BALANCE:17'
   AND sp.valid_span @> (now() AT TIME ZONE 'America/Edmonton')::date
   AND upper_inf(sp.txn_span);

Two predicates instead of one: the permanent cost of the model. Every read grows a valid-time containment test and a transaction-time test, and no version of bitemporality makes that go away. The only real question is whether it buys you something.

Note upper_inf(sp.txn_span) rather than sp.txn_span @> now(). Same rows, but the first is a clock-independent boolean over a single row, so it can back a partial index and cannot change answer mid-statement. Save containment for when you genuinely need to move along the transaction axis.

Rewinding the World: As Of a Valid Date

Now ask what was true on the third of March, according to everything we believe today.

WITH probe AS (SELECT DATE '2026-03-03' AS on_day)
SELECT s.amount,
       lower(s.valid_span) AS took_effect,
       upper(s.valid_span) AS superseded
  FROM service_price AS s, probe
 WHERE s.catalog_key = 'MOUNT_BALANCE:17'
   AND s.valid_span @> probe.on_day
   AND upper_inf(s.txn_span);

This is the query most teams think they want, and for reporting it usually is. It reflects corrections: if we discovered on the twelfth that the third was mispriced, this returns the corrected figure. That is right for a revenue restatement and wrong for a dispute, which is the distinction the next two queries exist to draw.

Rewinding the Record: As Of a Belief Instant

Same key, same day, but now pinned to what the system asserted at a particular moment.

SELECT p.amount,
       p.intent,
       lower(p.txn_span) AS asserted_at
  FROM service_price AS p
 WHERE p.catalog_key = 'MOUNT_BALANCE:17'
   AND p.valid_span @> DATE '2026-03-03'
   AND p.txn_span   @> TIMESTAMPTZ '2026-03-10 11:00-06';

If a correction landed on the twelfth, this returns the old figure — the one that was on the screen when someone printed the quote on the tenth. That is the answer to "why does my paper say something different," and it is not reachable from any single-axis schema.

The Full As-Of-As-Of, Which Is What Settles Arguments

Parameterize both coordinates and you have one query that subsumes the previous three.

CREATE FUNCTION price_at(
    p_key   text,
    p_day   date,
    p_asof  timestamptz
) RETURNS TABLE (state offering_state, amount numeric, note text, intent text)
LANGUAGE sql STABLE AS $$
    SELECT r.state, r.amount, r.note, r.intent
      FROM service_price AS r
     WHERE r.catalog_key = p_key
       AND r.valid_span @> p_day
       AND r.txn_span   @> p_asof;
$$;

price_at('MOUNT_BALANCE:17', '2026-03-03', now()) is current belief about the past. price_at('MOUNT_BALANCE:17', '2026-03-03', '2026-03-10 11:00-06') is past belief about the past. price_at('MOUNT_BALANCE:17', '2026-10-01', now()) is current belief about the future, which is exactly how you answer "what will the winter tire changeover rate be in October" without a separate scheduling table.

The function returns at most one row, guaranteed by the exclusion constraint rather than by hope. That guarantee is why I am comfortable putting a TABLE return type on it instead of defensively aggregating.

Recording a Correction Without Erasing What You Believed

Here is where naive implementations break. Somebody discovers that the figure published for March was wrong. The temptation is UPDATE service_price SET amount = ... WHERE .... Do that and you have destroyed the only copy of what the quote on the tenth was based on.

The correct operation has three parts, in one transaction, at one instant:

Close the transaction span of every currently-believed row whose valid span intersects the interval being corrected.
Insert the corrected row or rows covering the interval.
Re-insert the remainders — the parts of the closed rows' valid spans that fall outside the corrected interval — as fresh rows with the new transaction lower bound.

Step three is the one people forget, and forgetting it silently deletes history at the edges. If the old row was valid from January 1st onward and the correction covers only March, you must reassert January-through-February and April-onward, or those periods now have no applicable row at all.

PostgreSQL 14 and later make the remainder computation pleasant, because multiranges support difference:

CREATE FUNCTION restate_price(
    p_key    text,
    p_span   daterange,
    p_state  offering_state,
    p_amount numeric,
    p_intent text,
    p_who    text,
    p_note   text DEFAULT NULL
) RETURNS void
LANGUAGE plpgsql AS $$
DECLARE
    t_now   timestamptz := transaction_timestamp();
    victim  record;
    leftover daterange;
BEGIN
    FOR victim IN
        SELECT * FROM service_price
         WHERE catalog_key = p_key
           AND upper_inf(txn_span)
           AND valid_span && p_span
         FOR UPDATE
    LOOP
        UPDATE service_price
           SET txn_span = tstzrange(lower(txn_span), t_now, '[)')
         WHERE row_id = victim.row_id;

        FOR leftover IN
            SELECT unnest(datemultirange(victim.valid_span) - datemultirange(p_span))
        LOOP
            INSERT INTO service_price
                (catalog_key, state, amount, valid_span, txn_span, authored_by, intent, note)
            VALUES
                (victim.catalog_key, victim.state, victim.amount, leftover,
                 tstzrange(t_now, NULL, '[)'), p_who, 'carried_forward', victim.note);
        END LOOP;
    END LOOP;

    INSERT INTO service_price
        (catalog_key, state, amount, valid_span, txn_span, authored_by, intent, note)
    VALUES
        (p_key, p_state, p_amount, p_span, tstzrange(t_now, NULL, '[)'), p_who, p_intent, p_note);
END;
$$;

transaction_timestamp() is doing critical work here. Close the old span at one instant and open the new one at a slightly later instant — which is exactly what clock_timestamp() hands you — and there exists a real, microseconds-wide instant at which this key has no applicable row. A transaction-time probe landing in that window returns nothing. It will land there roughly never, until the once it does and you lose an afternoon. A single instant for the whole transaction closes the seam by construction.

FOR UPDATE matters too. Two concurrent restatements over overlapping intervals would otherwise read the same open rows, close them, and insert; the exclusion constraint catches the overlap and aborts one, which is safe but produces a baffling error. Locking the victims first turns that into an ordinary serialization wait.

Fixing the Past Versus Scheduling the Future

Both a backdated correction and a future-dated change have lower(valid_span) <> lower(txn_span). The sign of the difference separates them:

SELECT catalog_key,
       intent,
       lower(valid_span) AS effective_from,
       lower(txn_span)::date AS entered_on,
       CASE
         WHEN lower(valid_span) > lower(txn_span)::date THEN 'ahead of record'
         WHEN lower(valid_span) < lower(txn_span)::date THEN 'behind record'
         ELSE 'same day'
       END AS posture
  FROM service_price
 WHERE upper_inf(txn_span)
 ORDER BY lower(txn_span) DESC;

That derivation is fine for a dashboard and insufficient for anything else, which is why intent is stored rather than computed. Take two rows both sitting "behind record" by eleven days. In one, a colleague fat-fingered a figure and we fixed it. In the other, a supplier restated a line and we passed it through. The database sees identical geometry; the business sees two very different conversations with whoever was quoted in between. Geometry does not encode responsibility. Store the reason at write time — you will never recover it later.

Future-dated rows have their own hazard, which is that they are visible. A row with valid_span starting October 1st is in the table in late September, currently believed, and any query that forgets the valid-time predicate will find it. It gets worse with more than one reader. A counter terminal and an online reservation form consume the same rows and will not be updated on the same day. This is the likeliest leak in a bitemporal catalogue: not the exotic queries, but a reporting script that joins on catalog_key and filters only on upper_inf(txn_span) because the author was thinking about "current rows." Current in transaction time is not current in valid time. They are orthogonal, and the vocabulary does not help.

Restatement, and the Quotes Already Out the Door

The supplier says a line was mispriced since the first. You restate. Now: what about the quotes you handed out in between?

This is not a database question, but the database determines whether it is answerable. The rule is that any document you emit which contains a price must persist the coordinates it was priced at, not just the number. Beyond its own identity, a quote line needs three fields:

CREATE TABLE quote_line (
    quote_line_id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    quote_id      bigint      NOT NULL,
    catalog_key   text        NOT NULL,
    service_day   date        NOT NULL,
    priced_asof   timestamptz NOT NULL,
    amount_shown  numeric(10,2) NOT NULL
);

service_day is the valid-time coordinate, priced_asof is the transaction-time coordinate, and amount_shown is a denormalized copy so that the document renders identically forever even if someone drops the whole catalogue. With those, "why did we quote this figure" is reconstructible exactly:

SELECT q.quote_id,
       q.amount_shown,
       reconstructed.amount AS believed_then,
       current_view.amount  AS believed_now
  FROM quote_line AS q
  CROSS JOIN LATERAL price_at(q.catalog_key, q.service_day, q.priced_asof) AS reconstructed
  CROSS JOIN LATERAL price_at(q.catalog_key, q.service_day, now())         AS current_view
 WHERE q.quote_id = 4711;

If amount_shown and believed_then disagree, you have a bug in the quoting path and you can prove it. If believed_then and believed_now disagree, you have a restatement and you can list every affected document with one query rather than by memory. For a fleet account reconciling thirty vehicles at month-end, that list is the difference between a five-minute conversation and a spreadsheet argument.

What you then do about those quotes is policy, and the schema should stay out of it. Honour the old figure, reissue, absorb the difference — all defensible. But none of the three is even available if the quote stored a bare number with no coordinates, because you cannot identify which documents were affected.

We Stopped Offering It Versus We Never Offered It

Absence is the most under-modeled concept in catalogues, and bitemporality makes the distinctions crisp instead of ambiguous.

We never offered it. No rows for that key at any coordinate. price_at returns zero rows for every probe. This is the only case where genuine absence is correct.

We stopped offering it as of a date. The world changed. Close the valid span of the priced row at that date and insert a not_offered row valid from that date onward. Historical valid-time queries still return the old price, which is correct — it was offered then. A seasonal mobile service line is exactly this shape — available, then not, then available again — and if it is also priced differently across the areas it covers, each of those spans has its own history. All of them should remain readable rather than being overwritten by whatever is true today.

We never should have listed it. Our belief was wrong, not the world. Close the transaction span with no replacement row. Now current queries find nothing, and — crucially — as-of-valid-time queries also find nothing, because there is no currently-believed row covering that date. But as-of-transaction-time queries still show what we wrongly asserted, which is what you need when someone was quoted from a listing that should never have existed.

Those three collapse into one indistinguishable state under soft deletes. Under two time axes they are three distinct geometries, and you can tell them apart with a query rather than an interview.

The state enum earns its keep here. A not_offered row is a positive assertion of unavailability with an author and a timestamp on it, not a hole for some future reader to interpret. on_request covers the case that always turns up eventually — commercial and oversize work where the figure depends on the vehicle and no catalogue entry would be honest. "We have no price" and "priced individually" are different facts.

A Worked Example, With Deliberately Fake Numbers

Every figure below is invented for the example. Say the key is MOUNT_BALANCE:17 and the timeline runs as follows.

September 28th, 2025, 14:22. We record that from October 1st the rate is $45, unbounded above. One row: valid [2025-10-01, ∞), transaction [2025-09-28 14:22, ∞), intent scheduled.

October 1st, 2025. Nothing happens in the database. The row that was future-dated is now current, purely because the calendar moved. No write, no trigger, no job. This is one of the quiet pleasures of valid-time modeling.

March 1st, 2026, 08:00. We record a spring rate of $39, valid from March 1st. restate_price closes the October row's transaction span, inserts the remainder [2025-10-01, 2026-03-01) at $45, and inserts [2026-03-01, ∞) at $39. Three rows now, two of them currently believed.

March 10th, 11:00. A fleet account asks for a written figure covering a service visit that already happened on March 3rd. The document is generated that morning showing $39, and the line it writes stores service_day = 2026-03-03, priced_asof = 2026-03-10 11:00-06.

March 12th, 16:40. We discover the spring figure should have been $41 all along. restate_price runs again with valid span [2026-03-01, ∞), intent correction.

The table now looks like this. Transaction upper bounds are shown as ∞ where the row is still believed:

row	valid span	transaction span	amount	intent
1	`[2025-10-01, ∞)`	`[2025-09-28 14:22, 2026-03-01 08:00)`	45.00	scheduled
2	`[2025-10-01, 2026-03-01)`	`[2026-03-01 08:00, ∞)`	45.00	carried_forward
3	`[2026-03-01, ∞)`	`[2026-03-01 08:00, 2026-03-12 16:40)`	39.00	scheduled
4	`[2026-03-01, ∞)`	`[2026-03-12 16:40, ∞)`	41.00	correction

Four rows where a single-axis schema would have one row and a support conversation. Now run the probes:

price_at(key, '2026-03-03', now()) hits row 4. Answer: 41.00. What we now believe was true that day.
price_at(key, '2026-03-03', '2026-03-10 11:00-06') hits row 3. Answer: 39.00. What the printed quote was based on, recoverable two years later.
price_at(key, '2025-11-15', now()) hits row 2. Answer: 45.00, carried forward untouched through two restatements.
price_at(key, '2025-11-15', '2026-02-01 09:00-07') hits row 1. Same amount, different row, because in February we believed it via a different assertion.

That last pair is the one that convinces people. The answer is the same but the provenance is not, and only one of the two rows can be cited in a conversation about what the system said in February.

When a Business Date Meets an Absolute Instant

A brief hazard, because it is a genuine trap rather than the subject of this piece.

valid_span is a daterange in the local business calendar. txn_span is a tstzrange, an absolute instant. Mixing them carelessly is how you get a price that takes effect at 5 p.m. the previous afternoon.

The specific failure: CURRENT_DATE in PostgreSQL is evaluated in the session's TimeZone setting. A connection pool that leaves TimeZone at UTC will, every evening after 6 p.m. Mountain Daylight Time, compute tomorrow's date. Your October 1st price goes live on the evening of September 30th for every query issued from that pool. Write the conversion explicitly — (now() AT TIME ZONE 'America/Edmonton')::date — and never rely on session configuration for a business-meaningful boundary.

The write-side rule follows: "effective October 1st" is a local business date and belongs in the table as the date 2026-10-01, not as an instant computed at write time. Conversion to an instant is a rendering concern for the edge, where the asking zone is known. Store the business date; derive the instant.

Indexes, Range Types, and What the Planner Will Actually Do

The exclusion constraint builds a GiST index over (catalog_key, valid_span, txn_span). It will service && and @> queries, and for genuine time-travel it is the right structure. It is not, however, the right structure for the hot path, and assuming it is will make your catalogue reads slower than the single-axis table they replaced.

The hot path is "current price for one key," which is extremely selective on catalog_key and then wants exactly the rows with an infinite transaction upper bound. In a table that only ever grows, currently-believed rows become an ever-shrinking fraction of the whole. That is a textbook partial index:

CREATE INDEX service_price_live
    ON service_price (catalog_key)
    INCLUDE (valid_span, state, amount)
 WHERE upper_inf(txn_span);

Note that valid_span sits in the INCLUDE payload, not in the key. A B-tree cannot answer containment, so putting a range in a key column buys nothing; carrying it as payload lets the containment filter run without a heap fetch. The index stays roughly the size of the live catalogue rather than the size of its entire history, and it does not grow when you restate. Pair it with the upper_inf() form of the predicate in the query — this is why I wrote the current-truth query that way rather than with txn_span @> now().

Three further planner notes worth knowing before you profile:

now() is STABLE, not VOLATILE, so Postgres evaluates it once per statement and can use it as an index-scan bound. clock_timestamp() is volatile and cannot be used that way. If you sprinkle clock_timestamp() through predicates for "accuracy," you will silently lose index usage on every one of them.
GiST gives the planner worse selectivity estimates for @> than B-tree does for equality. A query combining a very selective key equality with a range containment is usually better planned as a B-tree lookup plus a filter, which is exactly what the partial index encourages.
SP-GiST supports range types and often beats GiST on pure containment, but cannot back an exclusion constraint. If time-travel reporting becomes a real workload, a second SP-GiST index on valid_span is worth measuring. Measure it; do not assume it.

One sentence of realism about growth: a few thousand keys restated a handful of times a year stays trivially small for a decade. If your price catalogue needs partitioning, it is probably not a price catalogue.

Snapshot Views That Cannot Quietly Drift

Application developers should not be writing two temporal predicates on every read. Give them a view.

CREATE VIEW catalog_today AS
SELECT v.catalog_key,
       v.state,
       v.amount,
       v.currency,
       lower(v.valid_span) AS in_effect_since,
       upper(v.valid_span) AS in_effect_until
  FROM service_price AS v
 WHERE upper_inf(v.txn_span)
   AND v.valid_span @> (now() AT TIME ZONE 'America/Edmonton')::date;

A plain view is honest by construction: it is the query, so it cannot disagree with the query. Reach for a materialized view only when profiling says so, and when you do, make it self-describing. Carry the instant it was computed from as a column, so any consumer can verify the snapshot rather than trust it:

CREATE MATERIALIZED VIEW catalog_snapshot AS
SELECT now() AS derived_at, c.* FROM catalog_today AS c;

Then a scheduled job can assert equality between the materialized rows and a live recomputation, and fail loudly on mismatch. The failure mode you are protecting against is not staleness in the abstract — it is a materialized view that has silently stopped refreshing while every dashboard built on it continues to render confidently. A snapshot that carries its own derivation coordinate can be checked. One that does not, cannot.

One more trap: a "current price" cache keyed only on catalog_key throws away both axes at the cache layer and reintroduces the original problem a tier up. Cache the result of a coordinate pair, or do not cache.

Property Tests Over Generated Interval Sets

Example-based tests will not find the bugs in this model. The bugs live at boundaries — spans that touch, spans that nest, corrections that exactly cover a previous correction — and hand-written cases cluster around the shapes you already thought of.

Generate operation sequences instead: a random series of asserts, restatements, scheduled changes, and withdrawals against a small key space, with invariants checked after every step.

One craft note matters more than the framework you pick — generate dates from a small pool, not uniformly at random. Draw dates uniformly from a decade and adjacent or identical boundaries essentially never occur, so the boundary bugs this model exists to prevent go unexercised. Twenty or thirty candidate dates makes collisions common. Same for keys: three, not three thousand.

from datetime import date
from hypothesis import given, strategies as st

DAYS = [date(2026, m, d) for m in (1, 3, 4, 10) for d in (1, 15, 28)]
KEYS = ["MOUNT_BALANCE:17", "ROTATE:STD", "REPAIR:PATCH"]

spans = st.lists(st.sampled_from(DAYS), min_size=2, max_size=2, unique=True).map(
    lambda pair: (min(pair), max(pair))
)

ops = st.tuples(
    st.sampled_from(KEYS),
    spans,
    st.sampled_from(["priced", "not_offered"]),
    st.integers(min_value=20, max_value=90),
)

@given(st.lists(ops, min_size=1, max_size=25))
def test_sequence_preserves_invariants(sequence):
    with fresh_schema() as db:
        for key, (lo, hi), state, amount in sequence:
            db.restate(key, lo, hi, state, amount)
            assert_invariants(db)

The three keys differ structurally rather than cosmetically: a bundled operation, a flat-rate service, and a puncture repair — the entry most likely to sit in on_request, because whether a given injury is repairable at all gets decided at the vehicle, not in a price list. Homogeneous keys make for a lazy generator.

Shrinking is the reason to use a property framework rather than a loop with a random seed. When an invariant breaks after nineteen operations, the framework hands you back the minimal three-operation sequence that reproduces it, and that sequence is almost always immediately legible as a design flaw rather than a coding slip.

The Invariants I Would Assert

These are the assertions worth having, roughly in order of how often I would expect each to catch something.

One truth per coordinate. For every key, every date in a probe set, and every distinct transaction lower bound in the table, the count of applicable rows is zero or one. This duplicates the exclusion constraint deliberately — constraints get dropped during migrations and not always restored.

Transaction time is append-only. No row's lower(txn_span) ever changes, and upper(txn_span) goes from infinite to finite exactly once, never back. Diff a table snapshot across each generated operation; any other mutation is a write-path bug.

History is stable. For any instant t and date d, price_at(key, d, t) computed now equals the same probe computed later. This is the property that makes the model worth its cost and it is trivially easy to lose — one stray UPDATE ... SET amount does it. Record every answer as you go, re-check them all at the end.

Valid-time coverage is contiguous. Aggregate the valid spans of all currently-believed rows for a key: SELECT range_agg(valid_span) FROM service_price WHERE catalog_key = $1 AND upper_inf(txn_span). The result must be a multirange with exactly one component. More than one component means a restatement dropped a remainder — that is the step-three bug, and this assertion catches it immediately.

Reversal is not erasure. Apply a correction, then apply a second correction restoring the original figure. Current-truth queries must return the original answer; the row count must have strictly increased; and the intermediate belief must still be reachable by a transaction-time probe. Systems that fail this one usually have an "undo" feature that deletes rows.

Nothing before the beginning. For every key, a probe at a date before the earliest lower(valid_span) returns zero rows in every transaction coordinate. Coverage should be total forward from the first assertion and empty before it — never accidentally unbounded below, which is what happens when someone constructs a range with a NULL lower bound by mistake.

When This Is Too Much Machinery

I would not put this in every schema, and the honest version of this article has to say where the line is.

It is overkill when the data is naturally immutable — an events table already carries transaction time and has no valid time worth modeling. It is overkill when nobody outside the team ever sees a derived figure, since the payoff is defending a number to someone who did not compute it. And it is overkill when corrections are rare enough that a spreadsheet annotation is genuinely fine; I would rather a team admit that than get a temporal model subtly wrong.

The costs compound:

Every read grows two predicates, and every developer who joins has to learn why.
ORMs fight you. Most assume a row is a thing rather than an assertion about a thing, and the workarounds are ugly in every framework I have used.
"Current" becomes ambiguous in conversation. Current in valid time and current in transaction time are different, and people will conflate them verbally even when the code does not.
Backfilling a single-axis table is hard, because historical transaction time is exactly what the old schema discarded. Seed everything at one instant and be honest that pre-cutover history is unknown; you cannot manufacture it.

Consider uni-temporal first, because it is often enough. Valid time alone handles scheduled changes and gives you the seasonal rate movement story cleanly. Transaction time alone gives you audit. Reach for both only when corrections to the past are a normal part of operations rather than an emergency — and in any business where a supplier can restate a figure after the fact, they are.

Three questions I would use as the test. Can an external party dispute a number you produced? Is a figure ever restated retroactively by someone who is not you? Must you be able to reproduce a decision months later? Two yeses and I would build this. Three and there is no real alternative — a service catalogue where customers receive written quotes, suppliers revise prices after the fact, and commercial invoices get reconciled at month-end hits all three without trying.

What I Would Actually Build First

If I were starting this tomorrow for a catalogue of tire and oil-change services, I would not begin with the full model. I would begin with the daterange valid-time axis and the exclusion constraint, because scheduled seasonal changes are the immediate operational need and half-open intervals are the thing you cannot retrofit cheaply. Getting the interval convention right on day one costs nothing; changing it later means rewriting every boundary in the table.

Then I would add the transaction axis the first time somebody asks a question beginning "what did it say when." That question always arrives, usually within a season. Where a customer is quoted for a set of winter rubber on a Tuesday and arrives the following Monday, or an all-weather line is restated by a supplier mid-month, the gap between what was true and what we said is not an edge case. It is the ordinary weather.

The failure I would most want to avoid is the one that looks like success: a table with valid_from, valid_to, and an updated_at, which appears to be temporal and is not. It answers the world question and silently overwrites the record question, and it does so without ever producing an error. You find out it was wrong when someone is standing there with a printout, which is the worst possible moment to discover that your history is a single mutable column.

Two axes. Half-open intervals on both. One exclusion constraint. One function that writes, and nothing else that does. That is the whole design, and everything above is just the consequences of taking it seriously.

Open Is Not Available: Modeling Service Hours, DST Boundaries, and Interval Algebra

KMJ Tire Calgary — Tue, 18 Aug 2026 16:28:31 +0000

Open Is Not Available: Modeling Service Hours, DST Boundaries, and Interval Algebra

A Six-Hour Window That Holds Five Hours of Work

Ask a naive hours model how much working time sits between 00:00 and 06:00 local on 8 March 2026 in America/Edmonton, and it will confidently answer six hours. The right answer is five. Here is the REPL transcript that produced it, unedited:

>>> from datetime import datetime, timezone
>>> from zoneinfo import ZoneInfo
>>> yyc = ZoneInfo("America/Edmonton")
>>> a = datetime(2026, 3, 8, 0, 0, tzinfo=yyc)
>>> b = datetime(2026, 3, 8, 6, 0, tzinfo=yyc)
>>> b.replace(tzinfo=None) - a.replace(tzinfo=None)
datetime.timedelta(seconds=21600)
>>> b.astimezone(timezone.utc) - a.astimezone(timezone.utc)
datetime.timedelta(seconds=18000)

Twenty-one thousand six hundred seconds of wall clock. Eighteen thousand seconds of reality. An hour vanished into the spring-forward transition, and a system that promised customers six hours of throughput that morning had five hours of bay time to deliver it with. Nobody typed a wrong number anywhere. The arithmetic was performed on the wrong kind of quantity.

Let me be exact about what this article is, because that matters more than the code. KMJ Tire is a real tire and oil-change operation in Calgary, working in the America/Edmonton zone, with a violent seasonal changeover rush, walk-in traffic, and jobs whose durations vary by an order of magnitude. Those operational constraints are real and they are the reason the problem is interesting. The scheduling system described below is a design exercise. It is a model I reasoned through on paper and exercised in a Python REPL, not live production infrastructure that the business runs today. There is no deployment, no incident, no migration and no rollout behind any of this.

Every figure in this article — durations, bay counts, technician counts, grid sizes, the shape of a working day — is illustrative. I picked numbers that make the edge cases legible. Do not read them as published hours, as staffing levels, or as measured performance. The engineering claims are testable and I have tested them; the business numbers are pedagogy.

With that settled: the thesis is that "when are we open, and can this job fit" decomposes into three separate problems that most codebases fuse into one. There is a representation problem (what you persist), a resolution problem (how layered rules produce a concrete set of instants for a given date), and an algebra problem (how you combine open windows with busy windows and job durations to get a truthful answer). Fusing them is what produces the six-hour window that holds five hours.

Wall Clock Plus Zone Id, Never a Stored Offset

The first decision determines whether the rest of the system is possible. Opening hours are not instants. They are a rule that generates instants when applied to a date. "We open at seven" is a statement about a local clock face, and it stays true across the transition even though the underlying UTC instant moves by an hour twice a year.

So the storage shape is: a local wall-clock time with no offset attached, plus an IANA zone identifier that names the ruleset.

{
  "rule_set_id": "hours-v7",
  "location_id": "loc-yyc-main",
  "iana_zone": "America/Edmonton",
  "weekly": [
    { "weekday": "MON", "windows": [["07:30", "17:30"]] },
    { "weekday": "TUE", "windows": [["07:30", "17:30"]] },
    { "weekday": "WED", "windows": [["07:30", "17:30"]] },
    { "weekday": "THU", "windows": [["07:30", "17:30"]] },
    { "weekday": "FRI", "windows": [["07:30", "17:00"]] },
    { "weekday": "SAT", "windows": [["09:00", "14:00"]] },
    { "weekday": "SUN", "windows": [] }
  ]
}

(Illustrative rule set. The hour values are chosen to exercise the model, not published hours.)

Three properties earn their keep here. The times are strings on a 24-hour clock, so they survive JSON round-trips without a numeric timezone sneaking in. The zone is an identifier, not an offset, so tzdata updates flow through automatically. And the whole document has an id, hours-v7, which is the hook that later lets you explain why a quote issued three weeks ago said what it said.

Note what is absent: no -07:00, no -06:00, no "MST", no utc_offset_minutes: -420. Abbreviations like MST and MDT are display artifacts. They are not unique across the world, they are not stable over time, and no library should be asked to parse them back into a zone.

What Rots When You Persist an Offset

Storing 07:30-07:00 looks harmless in March and becomes wrong in April. The failure is not that the value is malformed; it is that the value was correct and then quietly stopped being correct, with no write to the row.

Walk the decay:

Day one. Someone records winter hours in January. -07:00 is accurate. Every query agrees.
Second Sunday in March. The zone shifts to -06:00. The stored row still says -07:00. Every generated instant is now an hour late in real terms, so the location appears to open at 08:30 to anyone rendering from the stored offset.
Someone notices. A patch job updates the offsets in spring. Now the November transition breaks them the other way.
A rule change lands. A jurisdiction changes its transition dates or abandons the change entirely. With a zone id, you consume a tzdata release and you are done. With stored offsets, you own a data migration and a backfill for every future-dated record you already emitted.

That last point is a live design pressure in Alberta specifically. The province has revisited the twice-yearly change more than once, including a 2021 referendum on permanent daylight time that was defeated. Nothing has changed, and I am not going to pretend otherwise — clocks in Calgary still move. But the possibility of a legislative change is exactly the argument for storing America/Edmonton rather than -07:00. A zone id makes a future policy shift somebody else's release note. A stored offset makes it your outage.

A subtler variant of the same mistake is persisting the instant instead of the rule. Materializing "opens at 2026-11-04T14:30:00Z" for every future date bakes today's tzdata predictions into your database, and those predictions are forecasts of current legislation rather than physical constants. Materialized instants are a cache, and like every cache they need an invalidation story tied to the tzdata version that produced them.

The Local Time That Never Happens

Between 02:00:00 and 02:59:59 local on 8 March 2026, America/Edmonton has no valid local time. The clock jumps from 01:59:59 MST straight to 03:00:00 MDT. Here is the transition at second granularity, printed from UTC so nothing is hidden:

>>> from datetime import timedelta
>>> u = datetime(2026, 3, 8, 8, 59, 59, tzinfo=timezone.utc)
>>> u.astimezone(yyc).isoformat()
'2026-03-08T01:59:59-07:00'
>>> (u + timedelta(seconds=1)).astimezone(yyc).isoformat()
'2026-03-08T03:00:00-06:00'

Now the dangerous part. Python's zoneinfo does not raise when you construct a local time inside that hole. It returns something, and what it returns depends on the fold attribute in a way that surprises nearly everyone the first time:

>>> ghost = datetime(2026, 3, 8, 2, 15, tzinfo=yyc)
>>> ghost.utcoffset(), ghost.tzname()
(datetime.timedelta(days=-1, seconds=61200), 'MST')
>>> ghost.astimezone(timezone.utc).isoformat()
'2026-03-08T09:15:00+00:00'
>>> ghost.astimezone(timezone.utc).astimezone(yyc).isoformat()
'2026-03-08T03:15:00-06:00'

Read that last line again. You constructed 02:15, converted to UTC, converted straight back, and got 03:15. The round-trip is not the identity. With fold=1 the same wall time resolves an hour the other way, to 01:15 local. PEP 495 defines this precisely — in a gap, fold=0 uses the offset in effect before the transition and fold=1 uses the offset after — but "defined" and "what you wanted" are different things, and a silent 60-minute swing in either direction is not a good default for a system that quotes finish times.

Different ecosystems handle the same hole differently, which is worth knowing if your stack is polyglot. Java's java.time shifts a gap time forward by the length of the gap, so 02:15 becomes 03:15 and it is documented. The Temporal proposal in JavaScript makes you choose with a disambiguation option and defaults to 'compatible', which also shifts forward. Python hands you a value and a fold flag and trusts you to have read the PEP. None of these are wrong. They are simply different policies, and if you do not pick one deliberately, you have inherited three.

The Local Time That Happens Twice

The autumn transition is the mirror image and it is worse, because nothing looks anomalous. On 2 November 2025, the local time 01:30 occurred twice in America/Edmonton, sixty minutes apart:

>>> early = datetime(2025, 11, 2, 1, 30, tzinfo=yyc, fold=0)
>>> late  = datetime(2025, 11, 2, 1, 30, tzinfo=yyc, fold=1)
>>> early.tzname(), early.astimezone(timezone.utc).isoformat()
('MDT', '2025-11-02T07:30:00+00:00')
>>> late.tzname(), late.astimezone(timezone.utc).isoformat()
('MST', '2025-11-02T08:30:00+00:00')
>>> late - early
datetime.timedelta(seconds=3600)

Both are legitimate instants. Both render identically in a local-time UI. If two rows in a work-order table say 01:30 and one carries fold=0 while the other carries fold=1, they are an hour apart and every naive equality check will insist they are the same moment. If your ORM drops the fold bit on the way to the database — and plenty of serialization paths do, because fold is not part of ISO 8601 — you have silently collapsed two distinct instants into one.

I used a 2025 date deliberately. It is historical, so it is stable in every tzdata release you are likely to have, which makes it a safe fixture. Future transitions are predictions, and pinning a test to a prediction is how a green suite turns red on a routine dependency bump.

Note also that the elapsed-time arithmetic runs the other way in autumn. The same 00:00-to-06:00 local window that shrank to five hours in March expands to seven hours on a fall-back date. A capacity planner that assumes 24-hour days is wrong twice a year in opposite directions, and the autumn error is the friendlier one only because it errs toward having more time than you promised.

Resolving an Edge on Purpose Instead of by Accident

The fix is to stop treating local-to-instant conversion as a cast and start treating it as a function with a policy argument. Classify first, then resolve according to what the value means.

from enum import Enum
from datetime import datetime, timezone
from zoneinfo import ZoneInfo

UTC = timezone.utc


class LocalKind(str, Enum):
    UNIQUE = "unique"
    AMBIGUOUS = "ambiguous"
    NONEXISTENT = "nonexistent"


def local_kind(zone: ZoneInfo, naive: datetime) -> LocalKind:
    """Classify a naive wall-clock time against a zone's transition table."""
    early = naive.replace(tzinfo=zone, fold=0)
    late = naive.replace(tzinfo=zone, fold=1)
    if early.utcoffset() == late.utcoffset():
        return LocalKind.UNIQUE
    round_trip = early.astimezone(UTC).astimezone(zone).replace(tzinfo=None)
    return LocalKind.AMBIGUOUS if round_trip == naive else LocalKind.NONEXISTENT

The classifier leans on one asymmetry: in an overlap, the wall time survives a UTC round-trip; in a gap, it does not. That is a three-line test with no hard-coded transition dates, and it works for any zone the database knows about, including the half-hour and forty-five-minute offsets that break assumptions elsewhere.

Resolution then depends on the role the value plays. An opening edge and a closing edge want opposite treatment during an overlap:

class Edge(str, Enum):
    OPENING = "opening"
    CLOSING = "closing"


def to_instant(zone: ZoneInfo, naive: datetime, edge: Edge) -> datetime:
    kind = local_kind(zone, naive)
    if kind is LocalKind.UNIQUE:
        return naive.replace(tzinfo=zone).astimezone(UTC)
    if kind is LocalKind.AMBIGUOUS:
        fold = 0 if edge is Edge.OPENING else 1
        return naive.replace(tzinfo=zone, fold=fold).astimezone(UTC)
    early = naive.replace(tzinfo=zone, fold=0)
    late = naive.replace(tzinfo=zone, fold=1)
    shifted = naive + (late.utcoffset() - early.utcoffset())
    if local_kind(zone, shifted) is not LocalKind.UNIQUE:
        raise ValueError(f"unresolvable wall time {naive} in {zone}")
    return shifted.replace(tzinfo=zone).astimezone(UTC)

Openings take the earliest candidate and closings take the latest, which widens the window across an ambiguous hour. That is the correct bias for describing hours — you do not want to tell someone the doors are shut while the doors are open. It is the wrong bias for committing to a finish time, where you want the pessimistic edge. If the same conversion serves both purposes in your codebase, split it. The policy belongs at the boundary between the hours model and whatever is asking.

The gap branch shifts forward by the size of the jump, matching java.time and Temporal's compatible mode. A stricter variant clamps to the transition instant itself, so a 02:15 opening resolves to exactly 03:00 rather than 03:15. Both are defensible; the guard clause exists because a jurisdiction with a two-hour jump would land the shifted value in a second anomaly, and I would rather see an exception than a plausible-looking wrong answer.

Worked Boundary: Concrete Instants for a Seventy-Five Minute Job

Here is the whole failure mode in one worked example, with every instant written out. Suppose an illustrative seasonal drop-off window runs 01:30 to 04:00 local on 8 March 2026, and a job needs 75 minutes of productive time. Naive wall-clock arithmetic says: start 01:30, finish 02:45, comfortably inside the window.

>>> start = datetime(2026, 3, 8, 1, 30, tzinfo=yyc)
>>> start.astimezone(timezone.utc).isoformat()
'2026-03-08T08:30:00+00:00'
>>> naive_end = start + timedelta(minutes=120)
>>> naive_end.isoformat()
'2026-03-08T03:30:00-06:00'
>>> naive_end.astimezone(timezone.utc) - start.astimezone(timezone.utc)
datetime.timedelta(seconds=3600)

Adding two hours of timedelta to an aware datetime moved the wall clock two hours and moved the instant one hour. Python's arithmetic on aware datetimes is wall-clock arithmetic; the offset is re-derived after the addition. So a job the model believed had 120 minutes of runway actually had 60.

The correct sequence is: resolve to an instant, do the arithmetic on the instant, then render back to local for display.

>>> true_end = (start.astimezone(timezone.utc) + timedelta(minutes=120)).astimezone(yyc)
>>> true_end.isoformat()
'2026-03-08T04:30:00-06:00'

Two hours of real work that begins at 01:30 finishes at 04:30 on the clock face, not 03:30. Every customer-visible time in the system is a rendering of an instant, and every calculation is done on instants. Concretely, for this window:

Quantity	Naive wall-clock answer	Instant-correct answer
Window 01:30 → 04:00 local	150 minutes	90 minutes
Latest start for 75 min of work	02:45 local	01:45 local (`08:45Z`)
Finish if started 01:30	02:45 local	03:45 local (`09:45Z`)
Finish if started 02:00	03:15 local	resolution error — 02:00 does not exist

The last row is the one that catches people. A 30-minute grid over that window generates 02:00 and 02:30 as candidate start times, and both are wall times that never occur. If your grid generator iterates in local time by adding timedelta(minutes=30) to a naive datetime, it will emit them happily. Generate candidate starts on the instant timeline and render them to local afterwards, and the ghosts simply never appear, because there is no instant that maps to them.

Layered Rules: Weekly Patterns, Overrides, and Statutory Days

Real opening hours are not one table. They are a stack of assertions made by different people at different times with different authority, and the interesting engineering is in how the stack collapses to an answer.

At minimum you need these layers:

Base weekly pattern. The default cadence. Lowest authority, always present.
Seasonal pattern. Extended hours through changeover season, effective over a date range. Overrides the base for the dates it covers.
Recurring intraday closure. A midday break, a shift handover, a weekly stock-count hour. Removes time rather than replacing a day.
Statutory holiday set. Jurisdiction-scoped, with its own effective range and provenance.
One-off date override. "Closing at noon that Friday." Applies to a single date.
Emergency closure. Highest authority. A furnace failure, a water main, a blizzard that keeps staff off Deerfoot. Wins over everything.

Two distinct kinds of layer live in that list, and conflating them is the usual bug. Some layers replace the day's windows outright. Others cut time out of whatever the day already had. A holiday replaces; a lunch break cuts. Modeling both as "a list of windows" and last-write-wins gives you a resolver whose behaviour depends on insertion order.

def span_for(zone: ZoneInfo, day: date, pair: tuple[str, str]) -> Span:
    opens, closes = (time.fromisoformat(value) for value in pair)
    return Span(
        to_instant(zone, datetime.combine(day, opens), Edge.OPENING),
        to_instant(zone, datetime.combine(day, closes), Edge.CLOSING),
    )


def resolve_day(layers, day, zone):
    """Collapse a layer stack into concrete open spans for one calendar date."""
    ranked = sorted(layers, key=lambda layer: -layer["priority"])
    base = next(
        (l for l in ranked if l["kind"] == "replace" and l["applies"](day)),
        None,
    )
    if base is None:
        return []
    spans = [span_for(zone, day, pair) for pair in base["windows"]]
    cuts = [
        span_for(zone, day, pair)
        for l in ranked
        if l["kind"] == "cut"
        and l["priority"] >= base["priority"]
        and l["applies"](day)
        for pair in l["windows"]
    ]
    return subtract(spans, cuts) if cuts else merge(spans)

That helper assumes both edges land on the same calendar date, which is true for the windows above and false for an overnight window; a window whose closing time is less than its opening time needs the closing edge combined with the following day. Handle it in span_for or forbid it in validation, but do not let it default to a span with end <= start, because the constructor will reject it at a point far from the rule that caused it.

The algorithm has exactly two rules and both are stated in the code: the highest-priority applicable replace layer establishes the day's shape, and every cut layer at or above that priority removes time from it. Cuts below the winning base are suppressed. That is a real semantic choice, not an accident, and the next section shows why it bites.

Precedence Is a Product Decision, Not an Implementation Detail

Run the resolver over an illustrative stack and watch the consequence:

layers = [
    {"name": "base weekly", "priority": 10, "kind": "replace",
     "applies": lambda d: d.weekday() < 5, "windows": [("08:00", "17:00")]},
    {"name": "seasonal", "priority": 20, "kind": "replace",
     "applies": lambda d: d.weekday() < 5 and date(2026, 3, 1) <= d <= date(2026, 5, 31),
     "windows": [("07:00", "18:00")]},
    {"name": "midday closure", "priority": 15, "kind": "cut",
     "applies": lambda d: True, "windows": [("12:00", "12:45")]},
    {"name": "statutory", "priority": 40, "kind": "replace",
     "applies": lambda d: d == date(2026, 4, 3), "windows": []},
]

Resolving three dates produces:

2026-03-10  [('07:00', '18:00')]
2026-04-03  []
2026-06-10  [('08:00', '12:00'), ('12:45', '17:00')]

On 10 March the midday closure disappears. Its priority of 15 sits below the seasonal layer's 20, so the rule suppresses it. In June, with the seasonal layer inactive and the base weekly layer winning at priority 10, the same closure applies normally.

Is that right? It depends entirely on what the business meant. If the midday break is a staffing reality that holds regardless of season, its priority is wrong and it should sit at 25. If the seasonal pattern exists precisely because the location runs straight through the middle of the day during changeover, then priority 15 encodes the intent correctly. There is no neutral default. What the code buys you is that the question becomes answerable by reading two integers instead of tracing insertion order through a merge function.

I would add one more thing to that stack in anything long-lived: every layer carries an author, an effective_from, and a free-text reason. When a resolved day looks wrong six months later, the fastest path to an answer is a resolver that can emit the winning layer's name alongside the spans it produced.

Alberta's Holiday List Belongs in Data, Not in an If-Statement

Statutory holidays are the layer most likely to be hard-coded, and they are the least suitable for it, because the list is a jurisdictional policy artifact rather than a fact about calendars.

Alberta's general-holiday list is not the same as Ontario's or British Columbia's. Alberta has Family Day on the third Monday in February. Heritage Day in August is an optional holiday here rather than a general one, which means different employers treat it differently and a single boolean cannot represent the situation. The 30 September observance is a federal holiday and its provincial treatment differs across the country. Several dates are computed rather than fixed — Good Friday moves with the ecclesiastical calendar, and 3 April 2026 falls on it, which is why the resolver above returned an empty span list for that date.

The design consequences:

Holidays are rows, keyed by jurisdiction, with an effective date range and a source citation. Not a set literal in a module.
A holiday row asserts that a date is a holiday, not what the hours are. Whether the location closes fully, opens short, or ignores the date entirely is a separate policy join. Plenty of service businesses work statutory days.
Computed dates get materialized into rows by a job with a horizon, and the materialization records which algorithm produced it.
"Observed on" is its own column. When a fixed-date holiday lands on a weekend, the observed day may shift, and payroll, hours and government offices do not always shift it the same way.

None of this is exotic. It is the same discipline you would apply to tax rates: the values change by jurisdiction and over time, so they live in versioned data with provenance, and the code reads them.

Half-Open Intervals and the Boundary Overlap Bug

Every interval in the system is half-open: [start, end). The start instant is included, the end instant is not. This is not stylistic.

Consider two jobs in one bay, the first ending at 10:00 and the second beginning at 10:00. With closed intervals [start, end], both contain the instant 10:00:00.000, so an overlap check reports a conflict on a perfectly legal back-to-back sequence. Loosen the check to fix that, and now genuinely overlapping intervals slip through at the boundary. Teams oscillate between these two bugs for years, usually by sprinkling + 1 second into comparisons, which merely relocates the problem to a finer resolution and makes it depend on the precision of the clock and the column type.

Half-open intervals dissolve it. The overlap predicate becomes a strict two-way inequality with no epsilon anywhere:

@dataclass(frozen=True, order=True)
class Span:
    start: datetime
    end: datetime

    def __post_init__(self) -> None:
        if self.start.tzinfo is None or self.end.tzinfo is None:
            raise ValueError("Span requires aware datetimes")
        if self.end <= self.start:
            raise ValueError(f"empty or inverted span: {self.start} .. {self.end}")

    @property
    def duration(self) -> timedelta:
        return self.end - self.start

    def overlaps(self, other: "Span") -> bool:
        return self.start < other.end and other.start < self.end

    def contains(self, moment: datetime) -> bool:
        return self.start <= moment < self.end

Two consequences fall out immediately. Adjacent spans do not overlap, so [08:00, 10:00) and [10:00, 11:00) coexist. And the durations of a partition sum exactly to the whole, with no double-counted boundary instants — which is what makes utilization arithmetic add up instead of drifting by a second per split.

The constructor rejects zero-length spans on purpose. A zero-length span is almost always a symptom: a date override that collapsed, a subtraction that consumed a window entirely, a parse that produced 17:00 for both edges. Letting it exist means it propagates into a merge and produces output that is hard to reason about. Rejecting it at the boundary turns a silent data problem into a loud one.

Merging, Subtracting, Intersecting

Three operations cover essentially every availability question. Merge normalizes an unordered pile of spans into a canonical disjoint set. Subtract removes busy time from open time. Intersect finds where two independently-constrained resources are simultaneously free.

def merge(spans: list[Span]) -> list[Span]:
    out: list[Span] = []
    for span in sorted(spans, key=lambda s: (s.start, s.end)):
        if out and span.start <= out[-1].end:
            if span.end > out[-1].end:
                out[-1] = Span(out[-1].start, span.end)
        else:
            out.append(span)
    return out


def subtract(base: list[Span], cuts: list[Span]) -> list[Span]:
    result: list[Span] = []
    for span in merge(base):
        pieces = [span]
        for cut in merge(cuts):
            nxt: list[Span] = []
            for piece in pieces:
                if not piece.overlaps(cut):
                    nxt.append(piece)
                    continue
                if cut.start > piece.start:
                    nxt.append(Span(piece.start, cut.start))
                if cut.end < piece.end:
                    nxt.append(Span(cut.end, piece.end))
            pieces = nxt
        result.extend(pieces)
    return result

The <= in merge is deliberate and it is the opposite of the < in overlaps. Adjacent spans do not overlap, but they should coalesce: [08:00, 10:00) and [10:00, 11:00) merge into [08:00, 11:00) because the union is contiguous. Getting these two comparisons backwards produces a system that either reports phantom conflicts or emits a fragmented free list where every 15-minute increment is its own span.

subtract is where the half-open discipline pays off visibly. When a cut lands strictly inside a span you get two pieces and the boundary instants land in exactly one of them. When a cut consumes a span entirely, both if branches fail and the piece vanishes without producing an empty Span that the constructor would reject.

Intersection composes the same primitives:

def intersect(left: list[Span], right: list[Span]) -> list[Span]:
    out = []
    for a in merge(left):
        for b in merge(right):
            lo, hi = max(a.start, b.start), min(a.end, b.end)
            if lo < hi:
                out.append(Span(lo, hi))
    return merge(out)

Quadratic, and completely fine at the scale of one location for one day. If you ever run it across a year of half-hour slots for a fleet of locations, a sweep-line over sorted boundaries gets you to linearithmic, but reach for that when a profiler asks you to and not before.

Work Duration Versus Elapsed Duration

A job has at least four durations and they are all different numbers.

Work duration is hands-on time. Buffer is the pull-in, paperwork, torque check and pull-out around it. Calendar duration is how much wall time the job occupies, which exceeds work plus buffer whenever the job pauses. Customer-perceived duration is arrival to keys-back, which includes the wait before anyone touches the vehicle.

A model that stores one number called duration will eventually be asked to be all four, and the resulting bugs hide well because every individual answer looks plausible.

Concretely: a seasonal changeover with a rebalance is a different shape of job from a puncture repair, which is a different shape again from an oil change. The seasonal changeover work involves four wheel positions with torque and pressure steps; a balance adds spin-up time per wheel that scales with how far out the assembly is; a puncture repair has an inspection step that can terminate the job early with a "not repairable" verdict. These are the tire and oil-change services the location performs, and each one has a different variance profile. A scheduler that treats them as interchangeable 60-minute blocks will be wrong in a different direction for each.

The modeling advice is unglamorous: store work_minutes and buffer_minutes as separate fields, derive calendar duration from the resolved open spans at query time, and never persist calendar duration as an attribute of the service type, because it is a function of when the job runs and not of what the job is.

The Last Viable Start Is Not Closing Time

This is the single most common off-by-a-job bug in service scheduling, and it survives in production systems for years because it only manifests near the end of the day.

If the location closes at 17:00 and a job needs 75 minutes of work plus 10 minutes of buffer, the last instant at which that job can start is 15:35. Not 17:00, and not 15:45 either — the buffer counts.

def latest_start(window: Span, work: timedelta, buffer: timedelta):
    cutoff = window.end - work - buffer
    return cutoff if cutoff >= window.start else None

The None return matters as much as the arithmetic. A window shorter than the job produces no viable start at all, and that is a normal condition rather than an error. A 30-minute gap between two committed jobs is real open time and it is unusable for a 75-minute job. Systems that return the window's start anyway, on the theory that "the location is open then," produce reservations that cannot finish.

Running the primitives over an illustrative day makes it concrete. Take a resolved day of [07:00, 18:00) with a midday cut of [12:00, 12:45), and a job of 75 minutes of work plus 10 minutes of buffer on a 15-minute grid:

free windows      : 07:00–12:00, 12:45–18:00
latest start (am) : 10:35
latest start (pm) : 16:35
grid starts       : 07:00, 07:15, ... 10:30  |  12:45, 13:00, ... 16:30

The grid truncates below the true cutoff, because 10:35 is not on a 15-minute boundary. That is the correct behaviour for an offered set of start times, but be aware that you are discarding five usable minutes in each window. Whether that matters depends on how tight capacity is; during a changeover rush it might, and a scheduler that offers off-grid start times when the grid would otherwise return nothing is a legitimate refinement.

Jobs That May Pause and Jobs That May Not

Some work can straddle a midday closure. A vehicle sitting on a hoist while staff are away is not necessarily a problem. Other work cannot: a job holding a shared resource, or one with a chemical or thermal step that has to run continuously, has to finish before the pause begins.

Two predicates, therefore, not one. Non-pausable jobs must fit entirely inside a single free span. Pausable jobs may consume time across several spans, and their calendar end is computed by walking productive time forward while skipping pauses:

def finish_by(start: datetime, work: timedelta, pauses: list[Span]) -> datetime:
    """Advance `work` of productive time from `start`, stepping over pauses."""
    remaining, cursor = work, start
    for pause in merge(pauses):
        if pause.end <= cursor:
            continue
        if pause.start >= cursor + remaining:
            break
        productive = pause.start - cursor
        if productive > timedelta(0):
            remaining -= productive
        cursor = max(cursor, pause.end)
    return cursor + remaining

Started at 11:30 with 75 minutes of work and a [12:00, 12:45) pause, this returns 13:30 — a calendar span of two hours for 75 minutes of work. That gap between 75 and 120 is exactly the number a customer-facing estimate needs and a technician-facing estimate does not.

The pausable flag belongs on the service type, and its default should be False. Wrongly marking a job pausable produces a promise the location cannot keep; wrongly marking it non-pausable costs you some scheduling density. Those are not symmetric costs.

Capacity as Constrained Resources: Bays, Technicians, a Hoist

Here is where "are we open" stops being sufficient. The location can be open, have an empty free window, and still be unable to take the job, because open hours and capacity are different predicates over different objects.

Model each physical or human constraint — every bay, every technician, the hoist — as its own resource with its own busy list:

{
  "resources": [
    {"id": "bay-1", "kind": "bay", "capabilities": ["changeover", "repair", "oil"]},
    {"id": "bay-2", "kind": "bay", "capabilities": ["changeover", "repair"]},
    {"id": "hoist-1", "kind": "hoist", "capabilities": ["oil"]},
    {"id": "tech-a", "kind": "tech", "capabilities": ["changeover", "repair", "oil"]},
    {"id": "tech-b", "kind": "tech", "capabilities": ["changeover"]}
  ],
  "requirements": {
    "changeover": {"bay": 1, "tech": 1},
    "oil": {"bay": 1, "tech": 1, "hoist": 1}
  }
}

(Illustrative resource inventory — invented for the model, not a description of any real floor plan or staffing level.)

Availability for a job type is then the union, over every valid assignment of resources, of the intersection of those resources' free time with the open windows:

def joint_windows(open_spans, busy_by_resource, need):
    options = [
        [subtract(open_spans, busy_by_resource.get(rid, [])) for rid in ids]
        for ids in need.values()
    ]
    found: list[Span] = []

    def walk(idx, acc):
        if idx == len(options):
            found.extend(acc)
            return
        for choice in options[idx]:
            nxt = intersect(acc, choice) if acc else choice
            if nxt:
                walk(idx + 1, nxt)

    walk(0, [])
    return merge(found)

With an open day of [07:00, 18:00), bay-1 busy 09:00–11:00, bay-2 busy 07:00–10:00, and tech-a busy 07:00–09:30, the joint availability is [10:00, 18:00). Neither bay alone explains that answer and neither does the technician. It falls out of the combination, which is the whole point.

Three refinements this sketch omits and a production model would want. Resources have their own hours — a part-timer's shift is a smaller window than the day's. Some resources are shared across concurrent jobs rather than exclusive to one. And the assignment search is a matching problem that grows unpleasant with resource count, so past a certain size you stop enumerating and start solving. Even the naive version, though, gets you the crucial distinction: the difference between "open" and "available" is a join, and code that skips the join over-promises.

Real constraints leak in here too, and they are the reason a model like this earns its complexity. Work that happens at a customer's site through a mobile service route consumes a technician without consuming a bay, and adds travel time that belongs in the buffer. Fleet work arrives in batches that need several resources at once and behaves nothing like a single-vehicle reservation. The geographic areas a location serves determine how much travel buffer a mobile job needs. Any of these can break a model that assumed one job means one bay.

Shape of the Availability Response

The API is where all this either stays honest or leaks. The rule I would enforce: the server does the zone math, always, and the client is never asked to reconstruct an instant from a local string.

{
  "query": {
    "location_id": "loc-yyc-main",
    "service_type": "changeover",
    "date_local": "2026-03-08",
    "rule_set_id": "hours-v7",
    "tzdata_version": "2026c"
  },
  "zone": "America/Edmonton",
  "open_spans": [
    {"start": "2026-03-08T14:00:00Z", "end": "2026-03-08T20:00:00Z",
     "local_start": "07:00", "local_end": "13:00"}
  ],
  "startable": [
    {"instant": "2026-03-08T14:00:00Z", "local": "07:00", "offset": "-07:00"},
    {"instant": "2026-03-08T14:30:00Z", "local": "07:30", "offset": "-07:00"}
  ],
  "notes": [
    {"code": "dst_gap_skipped", "detail": "local 02:00–03:00 does not exist on this date"}
  ]
}

(Illustrative payload. Values are constructed to show the shape.)

Four properties are doing work. Every time appears as an unambiguous instant and as a pre-rendered local string, so the client displays a string and reasons with an instant, and never converts. The offset field is present for display and debugging but is never the source of truth. The rule_set_id and tzdata_version make the response reproducible. And notes gives the resolver somewhere to explain itself, which is the difference between a support conversation that takes two minutes and one that takes a week.

Return open spans and startable instants as separate fields. They answer different questions — one is "are the doors open," the other is "can this specific job begin here" — and a client that has both can render a sensible UI without re-deriving the second from the first and getting the buffer wrong.

Versioning the Rule Set So an Old Quote Can Be Explained

Hours change. Seasonal patterns turn on and off, statutory rows get corrected, a one-off override gets added and later removed. If the rule set is mutable in place, then every quote you issued before the change becomes unexplainable, because the only way to justify it is to reconstruct rules that no longer exist.

Make the rule set immutable and content-addressed. Changing hours writes a new version and flips a pointer. A quote records the rule_set_id and the tzdata_version it resolved against. Then "why did the system offer 16:45 on that Thursday" becomes a query rather than an argument.

The tzdata version deserves its own field. Resolve a date six months out, let the zone database change that transition, and your stored instant will disagree with a freshly-resolved one without either being a bug. Recording the version turns that from a mystery into a diff — and in containerized deployments it also explains why two replicas built from different base images resolved the same future date differently.

An Edge-Case Table Worth Pinning to the Wall

These are the inputs I would put in a fixture file before writing a line of resolver code.

Case	Input	Expected behaviour
Spring gap, opening edge	wall 02:15 on a gap date	shift forward, never silently pick an offset
Spring gap, grid generation	30-min grid across 01:30–04:00	02:00 and 02:30 never emitted
Fall overlap, opening edge	wall 01:30, ambiguous	earliest instant (`fold=0`)
Fall overlap, closing edge	wall 01:30, ambiguous	latest instant (`fold=1`)
Overnight window	22:00 → 02:00 next day	one span crossing midnight, not two
Zero-length window	17:00 → 17:00	rejected at construction
Inverted window	17:00 → 08:00 same day	rejected, or explicitly overnight
Cut consumes window	closure covers the whole day	empty free list, not an empty span
Adjacent jobs	10:00 end, 10:00 start	no conflict
Job longer than window	90 min into a 45 min gap	no viable start
Holiday plus override	both apply to one date	highest priority wins, deterministically
Leap day	29 Feb on a weekly rule	resolves like any other date
Two cuts overlapping	12:00–12:45 and 12:30–13:00	merged before subtraction

Most of these are one assertion each. All of them are cheap to write and expensive to discover in production.

Property Tests Across a Transition

Example-based tests catch the cases you thought of. Properties catch the ones you did not. Four hold for any correct implementation of this model, in any zone.

Round-trip stability. For any instant t, rendering to local and resolving back yields t — except in an overlap, where the resolved value must be one of the two candidates and the choice must match the declared edge policy.

Monotonicity. If t1 < t2 as instants, then resolving both through the same pipeline preserves the ordering. This is the property that catches offset-based comparison bugs, because a naive implementation that compares wall-clock strings will invert the order across a fall-back hour.

Duration conservation. Subtracting a set of cuts from a set of spans and summing the durations of the result equals the total base duration minus the duration of the intersection of base and cuts. Off-by-one boundary handling breaks this immediately.

Idempotence. merge(merge(xs)) == merge(xs), and subtracting the same cut twice equals subtracting it once.

A generator that concentrates on the interesting region is worth more than one that samples a decade uniformly:

from hypothesis import given, strategies as st

TRANSITION_DATES = [date(2025, 11, 2), date(2026, 3, 8), date(2026, 11, 1)]

near_transition = st.builds(
    lambda d, m: datetime.combine(d, time(0, 0)) + timedelta(minutes=m),
    st.sampled_from(TRANSITION_DATES),
    st.integers(min_value=0, max_value=6 * 60),
)


@given(near_transition)
def test_merge_is_idempotent(anchor):
    spans = build_day_spans(anchor)
    assert merge(merge(spans)) == merge(spans)

Uniform sampling across a year hits a DST boundary in roughly one draw in four thousand at minute granularity. Sampling the six hours around known transitions hits it constantly. Bias the generator toward the cliff.

Golden Files, Pinned tzdata, and Frozen Clocks

Three testing disciplines, each catching a different class of failure.

Golden files. For a fixed rule set and a fixed list of dates, serialize the resolved spans to a checked-in file, so any resolver change that alters output arrives as a reviewable diff. Keep one per zone, and include at least one zone that is not your primary — something on a southern-hemisphere schedule, or with a half-hour offset, catches assumptions that America/Edmonton alone never exercises.

Pinned tzdata. Add the tzdata package as an explicit dependency and pin it, or your suite's correctness depends on whatever zone database the base image shipped, and a routine rebuild changes behaviour with no commit to blame. Assert the version in a test so an unintended bump fails loudly.

Frozen clocks. Every function here should take "now" as a parameter rather than reading it. Once now is an argument, "what does availability return at 16:50 on a Friday in changeover season" is a unit test rather than a stakeout. Where an ambient clock is unavoidable, freeze it at an interesting instant — one inside an ambiguous hour — not at a comfortable Tuesday afternoon.

One more habit: write tests that assert the instant, not the local rendering. A test that asserts '07:00' passes in both the correct and incorrect implementations across a transition. A test that asserts '2026-03-08T14:00:00Z' does not.

Failure Modes, Named

Naming a bug class makes it easier to spot in review. These are the ones I would put on a checklist.

Offset fossilization. A stored offset that was correct at write time and silently wrong after the next transition.
Ghost slot emission. Candidate start times generated by adding to naive local datetimes, producing wall times inside a gap.
Fold amnesia. Serialization that discards fold, collapsing two distinct instants during an overlap into one indistinguishable value.
Wall-clock arithmetic. Adding timedelta to an aware datetime and treating the result as elapsed time, as in the two-hour addition that advanced the instant by one hour.
Boundary conflict. Closed intervals reporting a conflict between a job ending at 10:00 and one starting at 10:00.
Closing-time promise. Offering a start time that equals the last open instant minus nothing, so the job cannot finish before the doors shut.
Layer order dependence. A resolver whose output depends on the order rules were inserted rather than a declared precedence.
Holiday hard-coding. A jurisdiction's statutory list embedded in code, so a correction requires a deploy.
Availability conflated with openness. Returning open windows as though they were bookable capacity, ignoring resource constraints entirely.

Every one of these produces answers that look right in a screenshot. That is what makes them expensive.

Where the Abstraction Meets the Bay Floor

The reason this domain rewards careful modeling is that the physical operation it describes is genuinely irregular, and the irregularity is not noise you can average away.

Demand is not uniform. Changeover season concentrates an enormous share of the year's winter tire work into a few weeks, driven by weather that does not consult a calendar. A model whose capacity assumptions are calibrated on a quiet July week will be catastrophically wrong in late October, and it will be wrong in the direction of over-promising. That is the direction that costs trust.

Job durations are not uniform either. A four-wheel changeover on a passenger vehicle and a wheel-off inspection on a light truck consume different amounts of the same resources. Whether a customer runs all-weather tires year-round or swaps twice annually changes how often they appear in the schedule at all. Understanding the basics of what a tire is telling you is what lets a service writer estimate a duration accurately, and an estimate is the input the whole model depends on. Garbage duration estimates produce a beautifully correct interval algebra over meaningless numbers.

Walk-ins break the closed-world assumption outright. Any model that treats the schedule as fully known is describing a system that does not exist, which is why real deployments reserve capacity rather than filling it — and why the online reservation form and the counter queue are two producers writing to one resource pool. Sizing that reservation is a forecasting problem sitting on top of the availability model, and it needs the availability model to be correct before it can be tuned at all.

There is a documentation angle too. A service writer who knows why the system refused a 16:45 start can explain it in one sentence instead of apologizing for software. A technician who can explain a load index or why a commercial job needs different resourcing is doing exactly what the notes field does in the API response: turning a refusal into a reason.

What I Would Build First

If I were starting this model tomorrow, the order would be: Span with half-open semantics and a validating constructor; merge, subtract and intersect with property tests; local_kind and a policy-carrying to_instant; then the layered resolver; then resources; then the API surface. Availability queries come last, because they are a composition of everything below them and they are the hardest thing to debug if any layer beneath is subtly wrong.

The single highest-leverage decision is the first one. Store wall-clock times with an IANA zone identifier, never an offset, and treat local-to-instant conversion as a function that takes a policy argument and can fail. Systems built that way have DST bugs that are annoying. Systems built the other way have DST bugs that are archaeological.

And keep the six-hour window that holds five hours somewhere visible. It is a two-line REPL session that disproves the intuition the entire naive design rests on, and it costs nothing to re-run whenever someone proposes storing an offset "just for the cache."

Staleness Budgets: Designing Freshness Guarantees for Supplier Price and Stock Feeds

KMJ Tire Calgary — Mon, 17 Aug 2026 16:18:17 +0000

Staleness Budgets: Designing Freshness Guarantees for Supplier Price and Stock Feeds

Every integration that reads another company's inventory is a claim about the past dressed up as a claim about the present. You cached a number at 06:04. A customer reads it at 14:52. Somewhere in between, a warehouse in Edmonton shipped the last four casings of that size to somebody else, and nobody told you.

The usual reaction is to shorten the refresh interval and move on. That reaction is wrong in an interesting way: it treats freshness as a knob rather than as a property you can specify, measure, and hold yourself accountable to. What follows is a design for treating it as the latter — a staleness budget per field class, derived from measured change rates and from the cost of being wrong at a specific decision point.

Concrete setting, because abstractions about "entities" get slippery fast: a tire retailer pulls sizes, brands, availability and landed cost from several distributor feeds. Someone asks whether a 225/45R17 can go on the vehicle Thursday. Answering requires three facts that belong to other companies and one that belongs to you. Everything below is a design exercise. All numbers in code, tables and worked examples are illustrative and synthetic — placeholders chosen to make the arithmetic legible, never real supplier data, real cost, or real availability.

The only honest question about somebody else's inventory

"Is it available?" is not answerable. It is a question about the current state of a system you cannot observe, and the observation you can make takes 200 milliseconds to travel and arrives describing a moment that has already passed.

The answerable version is: given that I last observed this value N seconds ago, what is the probability it has since changed, and what does being wrong cost me here? Both halves matter. A landed cost that drifted a little on a browse page costs mild embarrassment. The same drift on a confirmed reservation costs either margin or a phone conversation nobody enjoys. Same data, same age, completely different tolerance.

So the unit of design is not the cache. It is the pair (field class, decision). A staleness budget is the maximum age at which a value may still be used for a particular decision, chosen so the probability of being wrong stays under a target you picked on purpose. Write that budget down. Enforce it in code. Alarm when you violate it. Everything else in this article is machinery for making that sentence true.

Model freshness as data, not as a boolean

The first structural mistake is storing available: true. The second is storing available: true, updated_at: <timestamp> and treating those two columns as unrelated. They are one value. The timestamp is not metadata; it is half the meaning.

Three distinct instants deserve separate columns, and collapsing them will cost you a debugging afternoon eventually:

observed_at — when your process received the bytes. This is about your pipeline. It is the only one of the three you can fully trust, because you generated it from your own clock.
source_as_of — the instant the supplier asserts the value was true. Present in good feeds, absent in most. Untrusted input: clamp it, never let it exceed observed_at by more than a small skew allowance, and record when you had to clamp it.
valid_until — a supplier-asserted expiry, when they publish one. Rare, and worth honouring when it appears, because it is the only case where somebody else has told you their own budget.

Why not one column? Because retries, queue backlogs and replays decouple them. A delta message produced at 06:04 that sat in a stalled consumer until 09:30 has source_as_of = 06:04 and observed_at = 09:30. If you kept only one, you would either believe the data is three hours fresher than it is, or you would discard a perfectly good historical fact. You need both to compute age and to detect pipeline lag, which are different alarms with different owners.

from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from enum import Enum
from typing import Generic, TypeVar

T = TypeVar("T")


class FieldClass(str, Enum):
    PRICE = "price"
    AVAILABILITY = "availability"
    LEAD_TIME = "lead_time"
    DESCRIPTIVE = "descriptive"


@dataclass(frozen=True)
class Observed(Generic[T]):
    """A value plus everything needed to reason about how much to trust it."""

    value: T
    field_class: FieldClass
    source: str
    observed_at: datetime
    source_as_of: datetime | None = None
    valid_until: datetime | None = None

    @property
    def effective_as_of(self) -> datetime:
        """Prefer the supplier's assertion, but never let it run ahead of us."""
        if self.source_as_of is None:
            return self.observed_at
        return min(self.source_as_of, self.observed_at)

    def age(self, now: datetime) -> timedelta:
        return now - self.effective_as_of

    def expired(self, now: datetime) -> bool:
        return self.valid_until is not None and now > self.valid_until


def utcnow() -> datetime:
    return datetime.now(timezone.utc)

On the wire, make "we do not know" representable. A boolean plus an optional timestamp lets an unknown masquerade as a fresh false, and a discriminated union does not:

export type FieldClass = "price" | "availability" | "leadTime" | "descriptive";

export interface Observed<T> {
  readonly value: T;
  readonly fieldClass: FieldClass;
  readonly source: string;
  readonly observedAt: string;    // RFC 3339, always UTC, generated by us
  readonly sourceAsOf?: string;   // supplier's own assertion, when published
  readonly validUntil?: string;   // supplier-asserted expiry, when published
}

export type Freshness =
  | { readonly state: "fresh"; readonly ageSeconds: number }
  | { readonly state: "stale"; readonly ageSeconds: number; readonly budgetSeconds: number }
  | { readonly state: "unknown"; readonly reason: "never-observed" | "upstream-down" };

export interface Answer<T> {
  readonly data: Observed<T> | null;
  readonly freshness: Freshness;
}

That unknown variant is the whole point. A downstream renderer that has to destructure it cannot accidentally paint a confident green badge over a supplier outage.

Field classes decay at very different rates

Lump every attribute of a product into one record and you have implicitly declared that they all rot at the same speed. They do not, and the spread is enormous.

A tire's section width, aspect ratio and rim diameter never change for a given part number — those are identity, not state. The markings moulded into the sidewall are fixed at manufacture. A load index is a property of the design. If you are polling a supplier every fifteen minutes to re-learn that a tire is still 225 millimetres wide, you are spending your rate limit on the least interesting bytes in the payload.

Availability, by contrast, is a counter that other people decrement all day. Landed cost changes when a price file lands, when freight terms shift, or when a distributor's own pricing cycle turns over — bursty, not smooth. Lead time is a derived estimate that moves with warehouse routing.

Field class	Example fields	What drives change	Illustrative budget	Failure if stale
Identity	part number, size, construction	never (new SKU instead)	effectively unbounded	wrong product entirely
Descriptive	tread pattern name, speed rating, load index	catalogue revisions	30 days	mildly wrong copy
Lead time	days to depot, transfer route	routing and stocking policy	24 hours	a missed promise date
Price	landed cost, freight adder	price-file batches, freight terms	6 hours	margin error
Availability	units at each depot	every order anyone places	20 minutes	a commitment you cannot honour

Those budgets are placeholders for the shape of the argument, not measured production values. The point is the four orders of magnitude between the top row and the bottom one. Any design that cannot express that spread is throwing away information you already have.

Field classes also let you split storage sensibly. Descriptive attributes belong in a slowly-changing catalogue table refreshed by the nightly snapshot. Availability belongs in a hot table with a narrow row and an index built for age queries. Mixing them means every availability tick rewrites a row containing a 400-character marketing description, which is a fine way to melt your write amplification.

One global TTL is the wrong abstraction

A single TTL forces one number to satisfy every consumer, so it converges on whichever consumer is loudest. Set it to fifteen minutes and 95% of your request budget goes to re-fetching data that changes twice a year. Set it to six hours and you will confidently offer a size that went to zero before lunch.

There is a subtler problem. A TTL is a property of a record, but staleness tolerance is a property of an edge — the specific read, by a specific consumer, for a specific purpose. The same availability row is simultaneously fresh enough for a category listing page and far too old for a confirmation screen. Attaching the number to the row erases that distinction and forces the strictest consumer's requirement onto everyone.

The third problem is that TTLs are uniform in time while demand is not. In Calgary a chinook can move the temperature twenty degrees in an afternoon, and the volume of people suddenly interested in changeover work follows the thermometer with a lag of about a day. During the October ramp, availability on popular winter sizes churns hard; in July, the same rows sit untouched for weeks. A fixed interval is either wasteful in summer or dangerously slack in autumn, and it is usually both, at different times, for different SKUs.

So: budgets attach to (field class × decision), and refresh scheduling is a separate concern driven by observed volatility and observed demand. Conflating policy with scheduling is the root error that a global TTL encodes.

Measuring decay from your own history

You cannot derive a budget from first principles. You derive it from what your own data did last month.

Keep an append-only change log: every time a poll produces a value different from the stored one, write a row with the supplier, the SKU, the field class, the previous value, the new value, and both timestamps. This log is cheap — it only grows on change — and it is the input to everything else.

The naive estimator is changes_detected / total_observation_hours. It is biased low, and knowing why matters. If you poll every 20 minutes and a value bounces from 4 to 0 to 4 between polls, you record zero changes. Polling gives you interval-censored data: you learn only whether the value moved during a window, never how many times.

Under a constant-hazard assumption, the correction is one line of algebra. If changes arrive as a Poisson process with rate λ, the probability that at least one change occurs in a window of length T is 1 - exp(-λT). Estimate that probability as the fraction of polls that detected a difference, then invert:

import math


def hazard_from_polls(polls: int, changes_detected: int, interval_seconds: float) -> float:
    """Interval-censored estimate of change rate, in changes per second.

    We observe only whether a value differed between two consecutive reads, so a
    raw change count understates reality. Inverting the Poisson survival function
    recovers the underlying rate from the detection fraction.
    """
    if polls <= 0 or changes_detected <= 0 or interval_seconds <= 0:
        return 0.0
    detection_fraction = min(changes_detected / polls, 0.999)
    return -math.log(1.0 - detection_fraction) / interval_seconds


def ttl_for_error_budget(rate_per_second: float, target_error: float) -> float:
    """Oldest age at which P(value already moved) stays under target_error."""
    if rate_per_second <= 0.0:
        return math.inf
    if not 0.0 < target_error < 1.0:
        raise ValueError("target_error must be strictly between 0 and 1")
    return -math.log(1.0 - target_error) / rate_per_second

Bucket the estimate. Per-SKU rates over-fit wildly on long-tail parts you have observed nine times; a global rate hides the fact that a common winter size behaves nothing like a niche commercial fitment. Something like (supplier × field class × demand decile) is usually the right granularity, with shrinkage toward the bucket mean for sparse cells.

And then the honest caveat: constant hazard is a lie you adopt deliberately. Price changes are not memoryless — they cluster at whatever hour the distributor's batch job runs. Availability hazard tracks order flow, which has a weekday shape and a weather shape. Treat the exponential model as a floor for reasoning, then override it with the two things you actually know: known publication times, and known demand spikes.

From hazard rate to a number you can defend

With a rate in hand, the budget falls out of a target error probability you choose per decision.

Survival under constant hazard is P(unchanged after age t) = exp(-λt), so the age at which you first exceed an error tolerance ε is t = -ln(1 - ε) / λ. Small ε makes the numerator approximately ε itself, which gives a useful mental shortcut: the budget is roughly your error tolerance divided by the change rate.

Illustrative arithmetic, synthetic figures throughout. Suppose a popular winter size at one distributor shows a detected-change fraction of 0.08 per 20-minute poll during the autumn ramp. Then λ ≈ -ln(0.92) / 1200 s ≈ 6.95 × 10⁻⁵ per second. For a browse page where you accept a 10% chance of being wrong, the budget is -ln(0.90) / 6.95e-5 ≈ 1,516 seconds, roughly 25 minutes. For a firm commitment where you accept 1%, it collapses to -ln(0.99) / 6.95e-5 ≈ 145 seconds. Same data, same rate, an order of magnitude apart, and the second number is short enough that the only sane implementation is to revalidate at the moment of commitment rather than to poll harder.

Two refinements that earn their complexity:

Asymmetry. Not all changes hurt equally. Availability falling to zero is expensive; availability rising from 4 to 9 is free. Landed cost rising costs you margin; falling costs you nothing you will notice today. Estimate one-sided rates — the hazard of a harmful transition — and set budgets against those. In practice this roughly doubles usable budgets, because harmful moves are typically a minority of moves.

Decision-weighted ε. Publish a small table of tolerances rather than scattering magic numbers: listing pages 10%, quote generation 3%, reservation confirmation 1%, fleet commitments 0.5%. Whether those are the right values is a business argument, and the table is where you have it — once, in the open, instead of implicitly in seventeen different cache decorators.

A policy evaluator you can unit-test

Budgets are worthless as documentation. They need to be a function that returns a verdict, so that the decision to serve stale data is a recorded event rather than an accident.

BUDGET_SECONDS: dict[FieldClass, float] = {
    FieldClass.PRICE: 6 * 3600,
    FieldClass.AVAILABILITY: 20 * 60,
    FieldClass.LEAD_TIME: 24 * 3600,
    FieldClass.DESCRIPTIVE: 30 * 24 * 3600,
}

DEMAND_TIER_MULTIPLIER: dict[str, float] = {"hot": 0.25, "warm": 1.0, "cold": 4.0}


class Verdict(str, Enum):
    SERVE = "serve"
    SERVE_LABELLED = "serve_labelled"
    REVALIDATE_FIRST = "revalidate_first"
    REFUSE = "refuse"


@dataclass(frozen=True)
class Decision:
    verdict: Verdict
    age_seconds: float
    budget_seconds: float

    @property
    def budget_violated(self) -> bool:
        return self.age_seconds > self.budget_seconds


def budget_for(field_class: FieldClass, demand_tier: str) -> float:
    return BUDGET_SECONDS[field_class] * DEMAND_TIER_MULTIPLIER[demand_tier]


def evaluate(
    obs: Observed[object] | None,
    *,
    now: datetime,
    field_class: FieldClass,
    demand_tier: str = "warm",
    binding: bool,
) -> Decision:
    """Decide what may be done with a cached value.

    `binding` marks decisions that create an obligation to the customer. Those
    never accept stale input; everything else may degrade gracefully.
    """
    budget = budget_for(field_class, demand_tier)
    if obs is None:
        return Decision(Verdict.REVALIDATE_FIRST if binding else Verdict.REFUSE, math.inf, budget)

    age = obs.age(now).total_seconds()
    if obs.expired(now):
        return Decision(Verdict.REVALIDATE_FIRST, age, budget)
    if age <= budget:
        return Decision(Verdict.SERVE, age, budget)
    if binding:
        return Decision(Verdict.REVALIDATE_FIRST, age, budget)
    if age <= budget * 4.0:
        return Decision(Verdict.SERVE_LABELLED, age, budget)
    return Decision(Verdict.REFUSE, age, budget)

Four verdicts, not two. The interesting one is SERVE_LABELLED: past budget, not yet absurd, safe to show provided the interface admits its age. The budget * 4.0 cliff is a policy choice — beyond some multiple, a number stops being approximate and starts being fiction.

Pull, push, and the hybrid that survives contact

Every real integration ends up with three mechanisms, and each one exists because the other two have a specific hole.

The nightly full snapshot is your ground truth reset. It is the only mechanism that catches deletions, because deltas tell you what changed and are silent about what vanished. It bounds worst-case drift at 24 hours regardless of what else broke. Run it against a staging table, compare row counts against the previous run, and refuse to promote a snapshot whose count moved more than a threshold — a truncated file that parses cleanly is the classic way to zero out a catalogue at 03:00.

Intraday deltas are how you get minutes instead of hours. Webhooks, a message queue, an incremental endpoint keyed on a cursor. The rule with deltas is simple and universally violated: never assume completeness. Demand a monotonic sequence number per stream, track the highest one you have processed, and alarm on gaps. If the supplier will not give you a sequence, you cannot detect loss, and you must treat the delta stream as a latency optimisation rather than a correctness mechanism.

On-demand revalidation at the decision point is the only thing that makes commitments defensible. When someone is about to be told "yes, Thursday works," you spend one synchronous request against the supplier and you spend it right then. The budget arithmetic above showed why: a 1% tolerance on a volatile field yields a budget measured in low minutes, and no polling schedule you can afford will keep every SKU that fresh. You do not need every SKU that fresh. You need the one that is about to become a promise.

Hybrid, therefore, is not indecision. It is three different guarantees composed: bounded worst case from the snapshot, good typical case from deltas, and exactness where it counts from revalidation.

Conditional requests make aggressive polling cheap

Here is the mechanism people skip, and it is the one that changes the economics.

An HTTP 304 Not Modified costs a round trip and a few hundred bytes, and it tells you something enormously valuable: the value you already hold is still current as of now. That resets observed_at without transferring, parsing, or writing anything. Freshness without payload. Once you internalise that, polling frequency stops being a bandwidth question and becomes a request-count question, and request counts are far cheaper to buy.

from dataclasses import replace

import httpx


@dataclass(frozen=True)
class CacheEntry:
    payload: dict | None
    etag: str | None
    last_modified: str | None
    observed_at: datetime


def revalidate(client: httpx.Client, url: str, entry: CacheEntry) -> CacheEntry:
    """Refresh an entry, transferring bytes only when the resource moved."""
    headers: dict[str, str] = {}
    if entry.etag:
        headers["If-None-Match"] = entry.etag
    if entry.last_modified:
        headers["If-Modified-Since"] = entry.last_modified

    response = client.get(url, headers=headers, timeout=5.0)
    if response.status_code == 304:
        return replace(entry, observed_at=utcnow())

    response.raise_for_status()
    return CacheEntry(
        payload=response.json(),
        etag=response.headers.get("ETag"),
        last_modified=response.headers.get("Last-Modified"),
        observed_at=utcnow(),
    )

Details that bite:

Last-Modified has one-second granularity, so two changes inside the same second are indistinguishable and you can pin a stale body indefinitely. Prefer ETag when both are offered. Weak validators (W/"abc") mean semantic equivalence, not byte equality — fine for freshness, useless if you are checksumming.

Many distributor APIs support neither. Two fallbacks: ask for a lightweight digest endpoint returning a version stamp per SKU group, or hash the normalised payload yourself. Self-hashing does not save bandwidth, but it saves parsing, writes, downstream invalidation, and — importantly — it prevents a re-serialised-but-identical payload from creating a spurious "change" that corrupts your rate estimates. Normalise before hashing: sort keys, drop server-generated request IDs, drop the response timestamp.

Scheduling: priority, jitter, and a shared bucket

Fixed-interval polling spends uniform effort on non-uniform value. Replace it with a priority score and a work queue.

A serviceable score multiplies three factors: how much demand the SKU sees, how volatile its field class is at that supplier, and how far through its budget the current value has aged. Something like demand_weight × λ̂ × (age / budget), recomputed lazily when an item is popped. Items whose age exceeds budget dominate naturally, items nobody looks at sink, and a SKU that becomes popular climbs within one cycle.

Demand weight is where local knowledge pays. Sizes that fit the vehicles common on Deerfoot in December deserve tighter refresh than a fitment you have quoted twice this year, and the popularity of a given winter fitment versus an all-weather option shifts with the forecast, not with the calendar. Feed the score from actual read counts over a trailing window and it tracks reality without anyone maintaining a list.

Then jitter, because synchronised timers are a self-inflicted denial of service. Anything scheduled with interval and no spread will converge into a convoy — a nightly job at midnight, 40,000 SKUs whose timers were all seeded at deploy, a supplier that starts returning 429s at exactly 00:00:03.

import random
import time


def next_poll_at(now: float, interval_seconds: float, *, spread: float = 0.15) -> float:
    """Fixed cadence with proportional jitter so thousands of items never align."""
    return now + interval_seconds * random.uniform(1.0 - spread, 1.0 + spread)


def backoff_delay(attempt: int, *, base: float = 0.5, cap: float = 60.0) -> float:
    """Full-jitter exponential backoff: growing ceiling, uniform draw beneath it."""
    ceiling = min(cap, base * (2 ** attempt))
    return random.uniform(0.0, ceiling)


class TokenBucket:
    """Per-supplier rate limit shared by every worker.

    This in-process version is the reference model; production state lives in a
    single store so N workers draw from one pool rather than N pools.
    """

    def __init__(self, rate_per_second: float, burst: int) -> None:
        self.rate = rate_per_second
        self.burst = burst
        self._tokens = float(burst)
        self._checked = time.monotonic()

    def acquire(self, cost: float = 1.0) -> float:
        """Seconds to wait before proceeding; 0.0 means go immediately."""
        now = time.monotonic()
        self._tokens = min(self.burst, self._tokens + (now - self._checked) * self.rate)
        self._checked = now
        if self._tokens >= cost:
            self._tokens -= cost
            return 0.0
        return (cost - self._tokens) / self.rate

The shared-bucket point deserves emphasis. Per-process limits are not limits. Six workers each politely capped at two requests per second produce twelve, and when autoscaling adds four more during the autumn ramp you are at twenty and the supplier's abuse detection has opinions. One bucket per supplier, in one place, with cost weighted so a full snapshot pull consumes more tokens than a conditional probe.

Failing well: breakers, backoff, and negative caching

Retry policy for feeds is mercifully simple because reads are idempotent. Retry GET freely; budget the retries per logical request rather than per attempt, so a request with a 3-second deadline does not spend 40 seconds heroically retrying into a supplier that is plainly down.

Circuit breakers matter more here than in most integrations, because the failure mode is not just latency — it is that a hung supplier holds workers hostage while every SKU in the queue ages past its budget. Trip on error rate over a rolling window rather than on a raw count. Half-open with a single probe, and choose the probe deliberately: a known-stable descriptive endpoint, not the heaviest availability query. When the breaker is open, every read for that supplier returns unknown immediately, which is a far better answer than a 30-second timeout.

Negative caching is the underrated half. A SKU that returns 404 will keep returning 404, and re-asking 3,000 times an hour helps nobody. Cache the negative — with its own, shorter budget, because "does not exist" reverses more often than you would think when a distributor onboards a line. The hard rule: never negative-cache a 5xx or a timeout. Those mean "I could not ask," not "the answer is no," and conflating them turns a ninety-second blip into an hour of phantom unavailability. That distinction is worth a separate cache state, not a shared one.

Serve stale with a label, or fail closed

This is the decision that people get wrong most often, and the reason is that they ask "how stale is it?" when the question is "what happens if it is wrong?"

Two consequence classes, and you should be able to name which one every read belongs to:

Wasted click. A listing shows a size as available; the customer clicks through; the detail view revalidates and corrects. Cost: mild annoyance. Serve stale, label it, move on. Refusing to render anything because a feed is 40 minutes old produces a blank page, which is strictly worse than an approximate one.

Wrong commitment. Someone is told a specific set can go on Thursday. That sentence creates an obligation. If the casings are not there, the cost is a rescheduled reservation, a wasted bay hour, and a driver who took an afternoon off work. Fail closed: revalidate synchronously, and if the supplier will not answer, say "let me confirm and get back to you" rather than guessing.

The boundary between those worlds should be a type, not a convention. Make the commitment path take a Confirmed<T> that can only be constructed from a fresh revalidation, and the compiler will enforce what a code review will eventually miss. In practice this means the reservation flow — the one behind the scheduling page — physically cannot accept a value that came out of the cache without a successful probe attached.

Same logic applies to work that travels. A van going out to a customer's site carries a fixed load of inventory, and being wrong about what is on it is not a wasted click but a wasted trip across the city. Anything dispatched to a location in our coverage map gets the fail-closed treatment.

Out-of-order updates and idempotent upserts

Distributed delivery reorders things. A retried webhook from 06:04 arrives after a fresh one from 06:09 and, if your upsert is unconditional, quietly resurrects a five-minute-old price. This bug is invisible in testing and produces exactly the kind of intermittent wrongness that costs a week to trace.

The fix is a monotonic version per source and a conditional write.

create table supplier_offer (
  supplier_id      text        not null,
  sku              text        not null,
  price_cents      integer     not null,
  currency         char(3)     not null default 'CAD',
  available_units  integer,
  lead_time_days   smallint,
  source_version   bigint      not null,
  source_as_of     timestamptz,
  observed_at      timestamptz not null,
  valid_until      timestamptz,
  tombstoned       boolean     not null default false,
  primary key (supplier_id, sku)
);

create index supplier_offer_age_idx
  on supplier_offer (supplier_id, observed_at desc)
  where tombstoned = false;

And the write, which refuses to move backwards:

insert into supplier_offer as existing (
  supplier_id, sku, price_cents, available_units,
  lead_time_days, source_version, source_as_of, observed_at
)
values ($1, $2, $3, $4, $5, $6, $7, now())
on conflict (supplier_id, sku) do update
   set price_cents     = excluded.price_cents,
       available_units = excluded.available_units,
       lead_time_days  = excluded.lead_time_days,
       source_version  = excluded.source_version,
       source_as_of    = excluded.source_as_of,
       observed_at     = excluded.observed_at
 where excluded.source_version > existing.source_version;

The where on the do update branch is the entire mechanism. Replays become no-ops, out-of-order arrivals are dropped, and the statement is idempotent under any delivery order. Count the dropped ones — a rising rate of rejected-as-older writes is a good early signal that a consumer is lagging.

When the supplier publishes no version, synthesise one. Ranked preference: their own sequence number; failing that, source_as_of converted to microseconds; failing that, a per-batch counter combined with the batch's start time. Falling back to observed_at is legal but weak, because it makes the retry itself look newer than the original — precisely the case you were defending against.

Multi-source is where it gets genuinely awkward. If two distributors both stock a SKU, there is no single ordering, and a version vector keyed by source is the honest structure: keep each source's latest observation separately, and resolve at read time with an explicit rule (cheapest currently-available, or preferred-partner-first, or fastest to depot). Merging them into one row destroys the ability to answer "which supplier said that, and when?" — which is the first question anyone asks when a number looks wrong.

Tombstones instead of deletes, for the same reason. A row that disappears from a snapshot has been discontinued, and "we knew about this until Tuesday" is a much more useful state than a missing row that looks identical to a SKU you never ingested.

The reconciliation loop and the drift metric

Everything above is inference. Reconciliation is the part where you actually check.

Sample records on a schedule, fetch them fresh and unconditionally, and compare against what you were serving. The comparison yields the single most valuable number in the system: drift rate, the fraction of sampled records whose cached value was wrong while inside its budget. If that number exceeds the ε you designed for, your budgets are too generous and the arithmetic is not opinion any more.

Three design notes that make the difference between a useful loop and a decorative one:

Stratify the sample. Uniform sampling across 40,000 SKUs spends almost all its effort on the long tail, where nothing changes and nobody looks. Weight by read volume so the sample resembles the traffic. Report drift per stratum, because a 0.4% aggregate hiding 6% on your top fifty sizes is worse than useless.

Separate drift from loss. A record can be wrong because the value moved and the budget was too long (a budget problem), or because a delta message was never delivered (a pipeline problem). Distinguish them by checking whether the correct value's source version was one you had ever received. Different alarms, different owners, and conflating them sends the wrong team looking.

Sample the writes, not just the reads. Reconcile a slice of records that your delta stream claims to have updated recently. If a delta said "4 units" and the truth is 9, you have a transformation bug, not a freshness bug, and no amount of polling faster will fix it.

Surfacing age to humans and to downstream systems

Internally, freshness is a typed field on the response body. Not a header — headers get stripped by proxies, ignored by clients, and lost the moment somebody wraps your response in an envelope. Put it in the payload where the type system can see it, and make it non-optional so nobody can forget to handle it.

For humans, the design goal is to convert an engineering fact into a calibration cue without inducing anxiety. "Checked 6 minutes ago" does that. A green dot does not — it communicates certainty you have not earned. Rounding rules worth stealing: under 60 seconds say "just now"; under an hour, whole minutes; under a day, whole hours; beyond that, the date. Never round up into a friendlier bucket, because the entire value of the label is that it is conservative.

Context changes the wording more than the number does. Someone comparing all-season against winter-specific options on a browse page does not need a timestamp on every tile; a single "availability checked within the last 20 minutes" line at the top of the results is enough calibration. Someone on a confirmation screen deserves the exact age of the specific fact they are relying on, because that is the moment where the number becomes a promise.

For fleet customers the requirement is different again. A fleet operations integration consuming your API needs machine-readable freshness so their own planner can decide whether to trust a figure, and it needs the age of the oldest input to a derived number, not the newest. Composite freshness is a minimum, never an average.

Observability: histograms, violations, and the silence alarm

Instrument age at read time. Age at write time is a measure of your poller's diligence; age at read time is a measure of what customers actually experienced, and the two diverge badly whenever your scheduling priorities are misaligned with demand.

Metric	Shape	Why it earns its cardinality
Age at read	histogram by field class	p50 tells you the typical experience; p99 tells you the tail that generates complaints
Budget violation rate	ratio by field class × decision	the direct SLO; alarm here first
Drift rate	ratio from reconciliation	validates that the budgets themselves are honest
Revalidation latency	histogram at the commitment path	this one is on the synchronous path and shows up as user-visible delay
304 ratio	ratio per supplier	efficiency, and a collapse means validators broke
Rejected-as-older writes	counter	early warning of consumer lag or clock trouble

Then the alarm nobody builds until after it has hurt them: feed silence. An unchanged feed is almost always a broken feed, not a stable one. If a supplier's availability stream normally produces four thousand changes a day and produced eleven yesterday, something upstream is stuck — a credential expired, a cursor got pinned, a filter clause started matching nothing. Alarm on the absence of change, using a floor derived from that stream's own trailing history rather than a hand-picked constant.

Related pathologies worth their own checks: a 304 ratio that reaches exactly 100% for a whole day (a validator that stopped changing rather than content that stopped moving); record counts landing on suspiciously round numbers like 10,000 (a page limit silently truncating); and a snapshot whose row count drops by more than a few percent (a partial file). Each of these has produced a quiet catalogue corruption somewhere, and each is a five-line check.

Here is a read-log query that produces the top half of that table:

select
    field_class,
    count(*)                                                  as reads,
    percentile_disc(0.50) within group (order by age_ms)      as p50_age_ms,
    percentile_disc(0.99) within group (order by age_ms)      as p99_age_ms,
    round(avg((age_ms > budget_ms)::int)::numeric, 4)         as violation_rate
from freshness_read_log
where read_at >= now() - interval '7 days'
group by field_class
order by violation_rate desc;

Sample the read log rather than writing every read — one in a hundred is plenty for percentiles at any real volume, and the write amplification of logging every cache hit will outweigh the insight.

A worked example, entirely synthetic

Numbers below are illustrative placeholders invented for the arithmetic. They are not KMJ figures, not supplier figures, and not measured production values.

Setting: three distributors, 40,000 SKU-supplier pairs, an API allowance of 2 requests per second per supplier, so about 518,000 requests per supplier per day.

Naive uniform polling at 20 minutes needs 40,000 × 72 = 2.88M requests per day against each supplier. Over budget by 5.5×. This is where most teams give up and stretch the interval to two hours, quietly accepting a drift rate they never measure.

Now apply the structure. Split by field class: descriptive attributes ride the nightly snapshot and cost nothing intraday. Only availability and price need intraday attention, and only the demand-weighted head of the catalogue needs it often.

Tier	SKU-supplier pairs	Interval	Requests/day	Notes
Hot (top 3% by reads)	1,200	5 min	345,600	conditional; ~85% return 304
Warm	6,800	45 min	217,600	conditional
Cold	32,000	nightly only	32,000	snapshot rows, not individual requests
Revalidation at commitment	~400 events/day	on demand	400	unconditional, synchronous

Total intraday across all three suppliers is roughly 595,600 requests, about 199,000 per supplier — comfortably inside the 518,000 allowance, with headroom for the autumn ramp when hot-tier membership swells. Bytes transferred are dominated by the 304s, so actual bandwidth is a fraction of the naive plan even though request volume is only modestly lower.

Freshness outcome, using the illustrative λ from earlier: hot-tier availability carries a p99 read age near 5 minutes against a 5-minute budget (hot tier multiplier 0.25 × 20 min), warm tier sits near 45 minutes against 20, which sounds like a failure until you notice warm-tier reads are browse traffic where the tolerance is 10% and the labelled-stale path is fine. Commitments bypass the cache entirely. Three different guarantees, one system, and every one of them is written down and measured.

Failure modes worth designing against explicitly

The timestamp that means nothing. updated_at set by an ORM onUpdate hook, so it records when a row was written rather than when the value was true. Every freshness computation downstream is then measuring your own write traffic.
Clock skew as data corruption. A supplier's as_of five minutes in the future makes age negative, which makes everything look eternally fresh. Clamp, count the clamps, and alarm if the count grows.
Retry storms disguised as demand. A supplier slows down, your retries multiply, their rate limiter trips, everything becomes retries. Full jitter and a shared bucket, or this happens on your worst day.
The delta stream that silently stopped. No errors, no alerts, just a cursor that stopped advancing two days ago. Only a silence alarm catches this.
Negative caching a timeout. "I could not ask" gets stored as "no," and a brief outage turns into an hour of phantom unavailability.
The unconditional upsert. A replayed message reinstates old state. Conditional writes on a monotonic version, always.
Uniform reconciliation sampling. Drift measured almost entirely on parts nobody reads, producing a reassuring aggregate that says nothing about the head of the distribution.
Freshness in a header. Stripped by a proxy, dropped by a client wrapper, and now every consumer treats absence as fresh.
A composite that averages. A quote assembled from four supplier facts is exactly as fresh as its oldest input, and reporting the mean makes stale data look acceptable.
Descriptive fields on the hot path. Re-polling immutable specifications every fifteen minutes, then wondering where the rate limit went.

A compressed incident, and what it teaches

Sketch of the shape these things take, offered as an illustrative scenario rather than a report of a specific event.

Mid-October, a chinook collapses overnight and the forecast flips. Search volume for winter sizes triples inside twelve hours, which is the demand-side load spike anyone doing seasonal changeover work plans for. The hot tier of the polling scheduler swells accordingly, the shared token bucket starts throttling, and warm-tier items begin aging past budget.

Meanwhile — and independently — one distributor's delta stream stalls at 04:00. The nightly snapshot had run at 02:00, so every record looks recent enough. Availability continues to be served from a snapshot that is now nine hours old on the most volatile field in the system, during the busiest demand hour of the season.

What surfaces the problem is not the polling metrics, which look healthy. It is two things. The silence alarm fires because a stream that normally emits thousands of changes emitted forty. And the reconciliation loop's drift rate on hot-tier availability jumps from a fraction of a percent to double digits — records wrong while inside budget, which is precisely the signal that says "your inference is broken, stop trusting it."

The lesson is not "add more polling." It is that the two mechanisms that caught it were both mechanisms that check the system against reality instead of against itself. Poller dashboards measure whether your code ran. Drift and silence measure whether your code was right. Only one of those pairs is worth waking up for.

What to build first

If you are retrofitting this into an existing integration, the order matters, because each step makes the next one measurable.

Start with the three timestamps and a read log. You cannot argue about budgets without knowing your current age distribution, and most teams are startled by their own p99. Add the change log next; two weeks of it gives you real rates. Then write budgets down — badly at first, refined by the drift signal later — and put them behind a policy function rather than scattering constants.

After that, the commitment path: make binding decisions revalidate synchronously, and make the type system enforce it. That single change removes the most expensive category of error before you have optimised anything. Conditional requests come next, because they make everything else affordable. Reconciliation and the silence alarm after that. Adaptive scheduling last — it is the most fun to build and the least valuable until the measurement layer exists to tune it.

Underneath all of it is one commitment worth restating plainly. You are never going to know the true state of somebody else's warehouse. You can know how old your information is, how fast that kind of information decays, and what you are willing to risk at each decision point. A system that knows those three things and says so out loud is more trustworthy than one that hides an unknown behind a confident boolean — whether the consumer is a rendering engine, a fleet planner, or a person at a counter asking whether their existing set can be repaired or whether new rubber needs to be sourced and balanced this week.

Freshness is not a feature you add. It is a number you owe your users, and the only way to owe it honestly is to write it down first.

Money Math for a Tire Quote Engine: Integer Cents, One Rounding Policy, and a Paper Trail You Can Replay

KMJ Tire Calgary — Sun, 16 Aug 2026 16:16:04 +0000

Money Math for a Tire Quote Engine: Integer Cents, One Rounding Policy, and a Paper Trail You Can Replay

Quoting four winter tires sounds like arithmetic a ten-year-old could do: unit price times four, add the install labour, add the per-tire fees, add tax, done. Then you try to build it as software, and the ten-year-old's version starts disagreeing with the accountant's version by a cent. Sometimes two cents. Sometimes it disagrees with itself depending on which order the line items were entered. This article is about making that impossible by construction.

The ground rules: real constraints, illustrative system

Before anything else, the framing, stated plainly so nobody mistakes design for deployment. KMJ Tire is a real, working tire business in Calgary — the operational constraints in this article (tire quantities sold in twos and fours, per-tire environmental fees, 5% GST, "out-the-door" totals quoted to customers before any work happens) are its genuine daily reality. The quoting system described here, however, is a design exercise: a worked-through architecture for how such a system should handle money, not a description of live production infrastructure. Every dollar figure, every tire price, every fee amount in this article is illustrative — invented for the worked examples, not pulled from a price list. There are no incident reports here, no production metrics, no adoption numbers, because none exist. What you get instead is the interesting part: the reasoning.

Why is a tire quote a good vehicle for this topic? Because it is small enough to hold in your head and gnarly enough to exercise every classic money-handling failure. A single quote for winter tires composes at least five kinds of amounts — a unit price, a quantity multiplier, a flat per-unit levy, a labour charge, and a percentage tax — and the customer expects one number at the end that will still be the same number when they arrive to pay. That expectation, "the total you quoted is the total I pay," is the entire correctness contract. Everything below serves it.

Floating point is the wrong tool, and here is the receipt

Start with the demonstration everyone has seen and half of us have shipped anyway:

>>> 0.1 + 0.2
0.30000000000000004
>>> 0.1 + 0.2 == 0.3
False

IEEE 754 doubles represent numbers in binary fractions. One tenth has no finite binary expansion, the same way one third has no finite decimal expansion. So 0.1 is actually the nearest representable double, which is 0.1000000000000000055511151231257827…. Each arithmetic operation rounds its result to the nearest representable value, and those tiny errors are not random noise that cancels out — they accumulate directionally depending on the magnitudes and order of your operations.

For a quote engine the failure mode is subtler than the meme. You will not see $1,203.30000000000004 on an invoice, because everyone formats output to two decimals. The formatting hides the drift until two independently correct code paths disagree. Consider an illustrative quote line: a tire at $247.99 times 4 is 991.96. In doubles:

>>> 247.99 * 4
991.9599999999999
>>> round(247.99 * 4, 2)
991.96

Fine so far — round rescued it. Now let a percentage enter the picture. Apply an illustrative 3.5% adjustment to that extended amount, then 5% GST, and compare against computing the same thing in a different but algebraically equivalent order:

>>> a = round(round(247.99 * 4 * 0.965, 2) * 1.05, 2)
>>> b = round(247.99 * 4 * 0.965 * 1.05, 2)
>>> (a, b)
(1005.11, 1005.1)

One path says $1,005.11, the other $1,005.10. Both are "correct" implementations of an underspecified calculation. Neither is buggy in the compiler's eyes. The bug is that the specification never said where rounding happens, so two developers made two defensible choices and now the emailed quote disagrees with the point-of-sale screen by one cent. A cent sounds trivial until the accounting export refuses to reconcile, or until a customer notices the number changed between the estimate and the invoice — for a small business whose whole pitch is straight-dealing, that cent is reputational, not financial.

Two lessons fall out of this before we write a single type:

Binary floating point cannot faithfully represent decimal money. This is not a precision problem you can out-round; it is a representation mismatch.
Even with exact representation, the order and location of rounding is a policy decision that must be written down once and enforced everywhere, or equivalent formulas will diverge.

The rest of the article is those two lessons, taken seriously.

Integer cents: the representation that cannot lie

The boring, bulletproof fix: store money as an integer count of the smallest currency unit. In Canada that is the cent. $247.99 becomes 24799. Integer addition and multiplication are exact — a 64-bit signed integer holds about 92 quadrillion cents, which comfortably exceeds the gross domestic product of tires.

But a naked number or int labelled "cents" in a comment is an invitation to disaster, because someone will eventually add a cents value to a dollars value, or multiply two money values together (dollars-squared is not a currency). The representation wants a type. In TypeScript, a branded type plus a tiny algebra:

// A branded integer type: structurally a number, nominally Money.
type Cents = number & { readonly __brand: "Cents" };

function cents(n: number): Cents {
  if (!Number.isSafeInteger(n)) {
    throw new RangeError(`Money must be an integer cent count, got ${n}`);
  }
  return n as Cents;
}

const add = (a: Cents, b: Cents): Cents => cents(a + b);

// Multiplying money by a scalar quantity is legal…
const times = (a: Cents, qty: number): Cents => {
  if (!Number.isSafeInteger(qty)) throw new RangeError("quantity must be integral");
  return cents(a * qty);
};

// …but note there is deliberately no `multiply(Money, Money)`.

The point of the brand is that add(unitPriceCents, taxRateBasisPoints) fails to type-check. The compiler now enforces dimensional analysis: money plus money is money; money times a dimensionless integer is money; money times money is a compile error. Rates get their own representation — and here is a second trap worth naming. If you store 5% as the float 0.05, you have reintroduced binary fractions through the back door. Store rates as integer basis points (5% = 500 bp) or as an integer numerator over a fixed denominator, and define exactly one function that applies a rate to a money value:

type BasisPoints = number & { readonly __brand: "BasisPoints" };

/** The ONLY place a rate touches money. Rounding policy lives here. */
function applyRate(amount: Cents, rate: BasisPoints): Cents {
  const numerator = amount * rate;         // exact: integer * integer
  return roundDiv(numerator, 10_000);      // one documented rounding, see below
}

amount * rate is exact integer arithmetic; the only inexact step is the division by 10,000, and that step is centralized in one function whose rounding behaviour is documented and tested. This is the structural move that makes the whole design work: push every rounding decision into a single choke point. When rounding can only happen in one function, "which rounding mode do we use?" has exactly one answer, and "where does rounding happen?" is answerable by grepping for one name.

A note on alternatives, because they deserve a fair hearing. Python's decimal.Decimal and Java's BigDecimal are decimal floating point: they represent 0.1 exactly and let you set rounding modes explicitly. They are excellent, and for a system doing currency conversion or fractional-cent unit pricing (fuel at 154.9 cents/litre, say) they may be the better call-site ergonomics. For a single-currency quote engine where every externally visible amount is whole cents, integer cents win on three counts: they serialize trivially (JSON, SQL BIGINT, wire protocols — no locale or precision ambiguity), they are impossible to construct inexactly, and they make the rounding choke point obvious because division is the only operation that can lose information. Decimal makes rounding configurable per-context; integers make it impossible except where you built the door.

Anatomy of an out-the-door tire quote

To design the calculation, first inventory what actually goes into the number a Calgary tire counter gives a customer. When a shopper is comparing tires before a purchase, the meaningful figure is never the sticker price of one tire — it is the out-the-door total: everything, installed, taxes in. Illustratively, a four-tire quote composes:

Product lines. Unit price × quantity for each tire model. Usually one line of quantity 4, but a staggered fitment (different sizes front and rear) produces two lines of quantity 2 — which is exactly why per-line behaviour matters.
Per-unit environmental fees. Alberta operates a tire recycling program funded by a levy collected on new tire sales; the mechanics that matter to the engine are that the fee is per tire, is a flat amount rather than a percentage, and is itemized. (The actual current rate is set by the program, varies by tire class, and changes over time — the amounts used in this article's examples, like $5.00 per passenger tire, are illustrative placeholders, not a statement of the official rate.)
Labour and service lines. Mounting and wheel balancing, valve stems or TPMS service kits, possibly a disposal charge for the old set. Some are per-tire, some are flat.
Adjustments. A percentage or fixed-amount change to some subset of lines — the most policy-sensitive component, covered in its own section.
GST. Alberta has no provincial sales tax, so the only sales tax on a quote like this is the federal GST at 5%. One rate applied to a defined base — but which base, computed when, is precisely the kind of thing that must be specified rather than assumed.

Notice what is absent: nothing here requires fractional cents as an output. Intermediate math produces fractions (5% of $1,151.96 is $57.598), but every line a customer sees, and every number that posts to a ledger, is whole cents. That asymmetry — exact integers at the boundaries, controlled rounding in the middle — is the shape of the whole design.

Rounding is a policy, not an implementation detail

Here is the uncomfortable truth about rounding money: for amounts this size there is rarely a single legally mandated answer, but there is always a mandated consistency. Canada's GST guidance permits normal commercial rounding practices; what gets a business into trouble is not choosing half-up over half-even, it is being unable to say which one it uses, or using different ones in different code paths. So the deliverable is not "the correct rounding mode." The deliverable is one written sentence, enforced by one function, verified by tests. Something like:

Policy (illustrative): all rounding is round-half-up on the absolute value (half-away-from-zero), applied per tax-calculation and per-adjustment at the moment that value is produced; line extensions (integer unit price × integer quantity) never round because they are exact; the invoice total is the exact integer sum of already-rounded parts and is itself never rounded.

Every clause in that sentence forecloses a category of divergence. "Half-away-from-zero" pins the tie-breaking rule and handles negative adjustments symmetrically (a -$0.125 adjustment rounds to -$0.13, mirroring the positive case). "Per-calculation at the moment produced" pins where. "Extensions never round" documents that multiplication of integers needs no policy. "The total is a sum of rounded parts" means the bottom line is derived, never independently computed — so it cannot disagree with its own line items.

The implementation of the choke point, continuing the TypeScript sketch:

/** Round-half-away-from-zero integer division. The system's ONLY rounding site. */
function roundDiv(numerator: number, denominator: number): Cents {
  const q = Math.trunc(numerator / denominator);
  const r = Math.abs(numerator % denominator) * 2;
  const bump = r >= denominator ? Math.sign(numerator) : 0;
  return cents(q + bump);
}

Ten lines, and every cent of ambiguity in the system routes through them. If the policy ever changes — a jurisdiction mandates something, an auditor prefers something — it changes in one place, with a version stamp (more on that in the audit section, because "we changed rounding modes on date X" is exactly the sort of fact a replayable history must capture).

Per-line or per-invoice: pick where the tax rounds

The classic composition question: do you compute tax on each line and sum the rounded results, or sum the untaxed lines and compute tax once on the subtotal? Both are legitimate; they can differ by a cent or two per invoice; the difference is structural, not moral.

Watch them diverge on an illustrative staggered fitment — two front tires at $189.99, two rears at $204.49, GST 5%:

Line	Extension	5% of line	Rounded per line
Front pair	$379.98	$18.999	$19.00
Rear pair	$408.98	$20.449	$20.45
Sum of line taxes			$39.45

Per-invoice instead: subtotal $788.96, times 5% is $39.448, rounds to $39.44. One cent apart, both defensible, and a system that computes per-line in the quote screen but per-invoice in the export will disagree with itself forever, one reconciliation ticket at a time.

Considerations that actually decide it:

Per-invoice minimizes accumulated rounding steps (one rounding event per rate per invoice) and matches how a person with a calculator checks the math: subtotal, times 1.05, done. For a single-rate, single-jurisdiction quote engine it is the simpler mental model.
Per-line is what you want when lines can carry different tax treatments — a taxable product line next to an exempt one — or when lines must be independently exportable to systems that expect each row to carry its own tax. It also localizes the effect of voiding one line: remove the line, remove exactly its tax.
Hybrid reality: many engines compute per tax group — sum the lines sharing a tax treatment, apply the rate once per group. This gets per-invoice's minimal rounding with per-line's ability to handle mixed treatments, and it is the choice the worked example below uses.

Whichever you choose, encode it in the calculation-order document and in the property tests, because this is the single most common source of the off-by-a-cent class of bug.

Half-up, half-even, and why the tie-break matters less than you think

Round-half-up (2.5 → 3) is what humans expect from school. Round-half-to-even, "banker's rounding" (2.5 → 2, 3.5 → 4), exists because always rounding ties upward introduces a systematic upward bias: over many rounding events, half-up drifts totals up by a fraction of a cent per event on average, while half-even's ties alternate direction and cancel in aggregate. IEEE 754 defaults to half-even for exactly this reason, and Python's built-in round follows it — a genuine gotcha if you assumed schoolbook behaviour:

>>> round(2.5), round(3.5), round(0.125, 2)
(2, 4, 0.12)   # half-even, and 0.125 isn't even exactly 0.125 in binary

(That last value is a compound gotcha: the literal 0.125 is exact in binary, but 2.675 famously is not — round(2.675, 2) gives 2.67, not because of the tie rule but because the stored value is fractionally below the tie. Binary representation and tie-breaking failures interleave, which is one more argument for integers, where the tie is genuinely a tie.)

For a quote engine, here is the honest assessment: at retail scale the statistical bias between half-up and half-even is economically irrelevant — fractions of a cent across the number of rounding events a small operation generates. What is not irrelevant:

Explainability. Half-up is explainable at a counter in one sentence. Half-even requires explaining why $0.125 became $0.12 this time and $0.135 became $0.14. When a human will re-check the math on paper, matching human arithmetic has real value.
Cross-system agreement. If the accounting package, the payment terminal, and the tax authority's examples all use half-up (most retail-facing tooling does), choosing half-even buys you a permanent trickle of one-cent explanations.
Symmetry under negation. Whatever you choose, specify behaviour for negative amounts (refund lines, negative adjustments). "Half away from zero" makes a refund the exact mirror of the sale, which is what reversal logic wants.

So: half-away-from-zero for this design, chosen for legibility, documented in the policy sentence, enforced in roundDiv, and — critically — testable, because the tie cases (…5 at the last digit) are enumerable and belong in the unit suite as table-driven cases.

The quote as a pure function with a declared order

Everything so far becomes real in one place: a pure function from a quote's inputs to its computed totals. Pure meaning: no clock reads, no database reads, no config lookups inside — every input that affects the output arrives as an argument, including the tax rate, the fee schedule, and the policy version. Same inputs, same cents, forever. That property is what later makes auditability and idempotent recalculation nearly free.

interface QuoteInput {
  lines: ProductLine[];        // unit cents, integer qty, fee class, tax group
  services: ServiceLine[];     // flat or per-unit labour, in cents
  adjustments: Adjustment[];   // see the discount section
  feeScheduleVersion: string;  // e.g. "fees-2026-illustrative-v1"
  gstBasisPoints: BasisPoints; // 500 — passed in, never read from globals
  policyVersion: "rounding-half-away-v1";
}

interface QuoteResult {
  lineExtensions: Cents[];   // exact, unrounded-because-exact
  perUnitFees: Cents;        // Σ (feePerTire × qty), exact
  serviceTotal: Cents;       // exact sum of service lines
  adjustmentApplied: Cents;  // rounded once at computation, signed
  taxableBase: Cents;        // exact sum of taxable parts
  gst: Cents;                // applyRate(taxableBase, 500) — rounds once
  total: Cents;              // exact sum of the above — NEVER rounded
}

function computeQuote(input: QuoteInput): QuoteResult { /* … */ }

The declared calculation order — the second half of the specification, ranking with the rounding policy itself:

Extend each product line: unitCents × qty. Exact.
Extend per-unit fees: for each line, feeCents(feeClass) × qty; sum. Exact.
Sum service lines. Exact.
Apply adjustments to their declared targets (defined below), each producing a signed cents amount, rounded at the moment of computation. This is rounding site #1.
Assemble the taxable base: product extensions + fees + services + adjustments, per tax group. Exact sum of integers.
Apply GST per tax group: applyRate(base, 500). Rounding site #2.
Total: exact integer sum. No rounding exists at this step by construction — there is nothing left to round.

Two structural notes. First, the order is data, not folklore: policyVersion names it, and changing the order means minting a new version string. Second, purity is load-bearing. Because computeQuote cannot observe the world, the quote a customer received last month can be recomputed today by replaying last month's inputs — the fee schedule as versioned then, the rate as passed then — and it must produce identical cents. A function that secretly read "current GST rate" from config would make historical quotes unreproducible the moment anything changed.

One quote, end to end, in exact integers

Concreteness time. All figures illustrative. A customer wants four all-weather tires installed — the sort of no-swap-twice-a-year setup covered on the all-weather tires overview — with an install package and a seasonal-changeover-style mount-and-balance labour line.

Inputs, in cents:

Product:  4 × 21,499  (tire @ $214.99, tax group: GST)
Fee:      4 ×    500  (illustrative per-tire recycling levy, GST group)
Service:  1 ×  8,000  (install labour package, $80.00, GST group)
Adjust:   −250 bp on product lines only (illustrative 2.5% off tires)
GST:      500 bp

Following the declared order:

Product extension: 21_499 × 4 = 85_996. Exact.
Fees: 500 × 4 = 2_000. Exact.
Services: 8_000. Exact.
Adjustment: targets product extension only. 85_996 × (−250) = −21_499_000; divide by 10,000 → −2_149.9 → rounds away from zero → −2_150. (This is −$21.50.) One rounding event, recorded.
Taxable base: 85_996 + 2_000 + 8_000 − 2_150 = 93_846 → $938.46. Exact.
GST: 93_846 × 500 = 46_923_000; over 10,000 → 4_692.3 → 4_692 (no tie, plain truncation-side case, .3 rounds down). $46.92. Second and final rounding event.
Total: 93_846 + 4_692 = 98_538 → $985.38 out the door.

Exactly two rounding events, both at named sites, both reconstructible. Re-enter the same lines in any order, on any machine, in any decade: 98_538. Compare that determinism with the floating-point version from earlier, where algebraically equivalent orderings produced different formatted totals — the difference is not diligence, it is architecture.

Discounts: percentages and absolutes are different animals

Adjustments deserve their own type discipline because they are where well-meaning flexibility destroys invariants. The safe representation is a tagged union that makes the dangerous cases unrepresentable:

type Adjustment =
  | { kind: "percentage"; basisPoints: BasisPoints;  // e.g. −250 = 2.5% off
      target: "product-lines" | "services" | "line"; lineId?: string;
      reason: string }                                // mandatory, audited
  | { kind: "absolute"; amount: Cents;                // e.g. −1_500 = $15.00 off
      target: "line" | "quote-pre-tax"; lineId?: string;
      reason: string };

The rules this encoding enforces, and why each exists:

A percentage must name its base. "2.5% off" is meaningless until you say off what — the tire lines? Including levies? Including labour? The target field makes the base explicit, so the computed cents are a function of declared data. (Per-tire environmental levies are typically not discountable — the amount is remitted onward regardless of what the seller charges — which is an excellent illustration of why "percentage off everything" must not be the only representable adjustment.)
Percentages compute once, into cents, at step 4, and the cents are what's stored on the result. Never store "2.5% off" and re-derive it at display time from whatever the lines happen to be now — that re-derivation is how a later line edit silently changes an already-communicated figure.
Absolutes are already cents and never round, but they must declare whether they apply pre-tax (reducing the GST base — the normal case for a seller-funded price reduction) or post-tax (a payment against the total, which is not a price change at all and arguably belongs in a different structure entirely). Pre-tax is the default; post-tax should be rare and loudly typed.
Stacking order is policy. Two percentage adjustments: do they compose on the original base (additive: 10% + 5% = 15% off) or sequentially (compound: 14.5% off)? Neither is wrong; unspecified is wrong. The design picks sequential-in-list-order and the property tests pin it.
reason is mandatory. Not for the math — for the humans and the audit trail. An adjustment with no recorded rationale is the line item every future reader distrusts.

One more guard worth its weight: clamp. An absolute adjustment larger than its target line, or stacked percentages exceeding 100%, should fail validation rather than produce a negative line. Negative totals from over-discounting are a classic silent-corruption path into every downstream system.

Composing GST and per-tire levies without double-taxing or under-taxing

Tax composition questions are really "what is in the base?" questions, and the tire case has a genuinely instructive one: is the recycling levy itself subject to GST? In Canada, environmental handling fees of this style are generally treated as part of the consideration for the sale — meaning GST applies on top of the levy — but the correct move for a design article is not to bake a legal conclusion into code, it is to make the question a data question. Hence tax groups: every line, including fee lines, carries a tax-group tag, and the engine taxes whatever the group says to tax. If the treatment ever needs to change, it changes in the versioned fee schedule, not in the arithmetic.

The fee schedule as data, versioned like the policy:

interface FeeSchedule {
  version: string;               // "fees-2026-illustrative-v1"
  effectiveFrom: string;         // ISO date
  perUnit: Record<FeeClass, { amountCents: Cents; taxGroup: "gst" | "exempt" }>;
  // e.g. passenger: { amountCents: 500, taxGroup: "gst" }  ← illustrative
}

This shape handles the realities gracefully: levy amounts differ by tire class (a passenger tire and the tires on the trucks served by a commercial tire program carry different fee classes), amounts change when the program changes them, and historical quotes must keep pointing at the schedule version that priced them. GST composition then follows mechanically from the tax-group partition built in step 5 of the calculation order: sum each group exactly, apply each group's rate once, sum the results. No line is ever taxed twice because it belongs to exactly one group; no taxable line escapes because group membership is mandatory, not defaulted.

A brief word on the 5% itself: Alberta's lack of a provincial sales tax makes this the easy version of the problem — one rate, one group in the common case. The design still carries the tax-group machinery, because "we only have one tax" is exactly the assumption that hurts when a quote engine meets a second jurisdiction, an exempt fleet account, or a zero-rated line. The machinery costs one field and one loop; the assumption costs a rewrite.

Property-based tests: state the invariants, let the machine hunt

Example-based tests check the arithmetic you thought of. Property-based tests check the algebra you claimed. For a money engine the claims are crisp enough to be executable, which makes this one of the best property-testing domains there is. Using Python and Hypothesis for the sketches (fast-check is the TypeScript equivalent):

from hypothesis import given, strategies as st

lines = st.lists(
    st.tuples(st.integers(1, 100_000),   # unit cents ($0.01–$1,000)
              st.integers(1, 12)),       # quantity
    min_size=1, max_size=20)

@given(lines, st.randoms())
def test_total_invariant_under_reordering(ls, rnd):
    shuffled = ls[:]; rnd.shuffle(shuffled)
    assert compute_quote(ls).total == compute_quote(shuffled).total

@given(lines)
def test_total_equals_sum_of_parts(ls):
    r = compute_quote(ls)
    assert r.total == sum(r.line_extensions) + r.per_unit_fees \
                    + r.service_total + r.adjustment_applied + r.gst

The properties worth encoding for this engine, roughly in order of bug-finding yield:

Permutation invariance. Reordering lines never changes any total. This property is false in naive floating-point implementations (float addition is not associative) and true by construction here — which makes it the perfect canary: if it ever fails, someone reintroduced a float.
Parts-sum identity. The displayed total always equals the exact sum of displayed parts. This is the "invoice adds up on paper" guarantee, and it holds because the total is defined as that sum — the test guards against anyone "helpfully" recomputing it another way.
No-drift round-trip. Serialize a quote result to JSON and back, or write and re-read it through the persistence layer: every cents field is bit-identical. Trivial with integers, historically violated by anything that transits a float column or a locale-formatting layer.
Recompute stability. compute_quote(x) == compute_quote(x), and more usefully: recomputing from the stored inputs of a historical quote reproduces the stored outputs. This is the executable form of purity.
Bounded rounding error. Per-group tax differs from the unrounded real-number tax by strictly less than one cent, and the count of rounding events equals (number of adjustments + number of tax groups). Pinning the count is underrated: it catches a refactor that sneaks a third rounding site in.
Adjustment symmetry. Applying an adjustment and its exact negation yields the original totals — the refund-mirrors-sale property that half-away-from-zero was chosen to provide.
Monotonicity sanity. Adding a line with positive amounts never decreases the total; a clamped discount never produces a negative line. Cheap to state, embarrassing to fail.

Hypothesis will find the tie-break edges (amounts ending in exactly half a cent after rate application), the qty-zero and single-line degenerates, and adjacency effects between stacked adjustments faster than any hand-written table. Keep the hand-written table too — the worked example above belongs in it verbatim, as an executable specification.

The audit trail: append-only events, replayable prices

Now the operational half. A quoted price is a small promise, and promises need provenance: what was quoted, when, under which fee schedule, and why did revision 3 differ from revision 2? The design answer is an append-only event log — quote state is never updated in place; every change is a new immutable record, and "the quote" is a fold over its events.

CREATE TABLE quote_events (
  event_id      BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  quote_id      UUID        NOT NULL,
  revision      INT         NOT NULL,             -- 1, 2, 3… per quote
  event_type    TEXT        NOT NULL,             -- 'created' | 'line_added'
                                                  -- | 'line_removed' | 'adjustment_applied'
                                                  -- | 'reprice_requested' | 'superseded'
  payload       JSONB       NOT NULL,             -- full input delta, typed
  policy_version   TEXT     NOT NULL,             -- 'rounding-half-away-v1'
  fee_schedule_ver TEXT     NOT NULL,             -- 'fees-2026-illustrative-v1'
  computed_total   BIGINT   NOT NULL,             -- cents, result AFTER this event
  actor         TEXT        NOT NULL,             -- who or what made the change
  reason        TEXT        NOT NULL,             -- human-entered rationale
  occurred_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (quote_id, revision)
);
-- No UPDATE, no DELETE. Enforce with permissions, not discipline:
-- REVOKE UPDATE, DELETE ON quote_events FROM app_role;

What this structure buys, concretely:

Reconstruction. To answer "why was this customer quoted $985.38 on the 3rd?", replay events 1..n through the pure computeQuote with the recorded schedule and policy versions. Because the function is pure and the inputs are fully captured, the replay must land on computed_total — and storing that expected total in the event row turns every replay into a checksum. A mismatch means either data corruption or an unversioned behaviour change, both of which you urgently want to know about.
Diffable revisions. Revision 2 versus revision 3 is a structured diff of payloads: "rear line quantity 2 → 4, actor: counter-staff, reason: customer switched from pair to full set." The why travels with the what — this is the difference between an audit trail and a mere backup.
Supersession, not mutation. When a quote is re-priced because a new fee schedule took effect, the old revision remains fully intact and reproducible under its original schedule; a reprice_requested event creates the next revision under the new one. Nothing historical ever becomes false.
Honest timestamps. occurred_at is when the event was recorded, and it is the only clock in the system. The pure function takes no clock, so "what would this quote be if entered today" versus "what was it then" are both answerable, distinctly, without ambiguity about which question you asked.

The same discipline scales down and up. A single retail quote for a flat repair might have two events in its whole life; the multi-vehicle estimates a fleet account generates might accumulate dozens across weeks of back-and-forth. The event model does not care — the fold is the fold, and cheap immutable rows are the least expensive insurance a money system can buy.

Idempotent recalculation: same request, same cents, no surprises

"Idempotent" gets used loosely; here it means something specific and testable: recalculating a quote any number of times, from any starting point, converges on identical output, and requesting the same mutation twice produces one event, not two. Both halves matter and they are different mechanisms.

The first half is purity again, now with teeth. Because computeQuote is a function of (lines, services, adjustments, schedule version, rate, policy version) and nothing else, recalculation is safe to run anywhere, any time: on every event append, in a nightly verification sweep that replays recent quotes and compares checksums, in a migration dry-run. There is no "recalculate" button that might change the number — recalculation is verification, and if it would produce a different total, that is definitionally a new revision requiring a new event with a recorded cause, never a silent overwrite.

The second half is transport-level: the counter's browser retries a save; a webhook fires twice; a queued job redelivers. Standard fix, worth writing down because money systems are where duplicate mutations hurt most: every mutating request carries a client-generated idempotency key, and the event append is conditional on that key being unseen.

ALTER TABLE quote_events ADD COLUMN idempotency_key UUID NOT NULL;
CREATE UNIQUE INDEX ON quote_events (idempotency_key);
-- Retry with the same key → unique violation → return the ORIGINAL result, HTTP 200.

The retry does not error out from the client's perspective — it receives the same response the first attempt earned, which is the whole point: the caller cannot tell (and need not care) whether it was the first or the fourth delivery. Combined with the UNIQUE (quote_id, revision) constraint doing optimistic concurrency (two staff editing the same quote race to claim revision n+1; the loser re-reads and re-applies), the event log stays linear, duplicate-free, and calm under exactly the flaky-network conditions a real counter with a tablet on retail Wi-Fi will produce.

Schema sketches: the whole design on one page

Pulling the persistent shapes together, trimmed to essentials. Money columns are BIGINT cents everywhere — no NUMERIC(10,2) (which invites application-layer float conversion at the boundary) and absolutely no FLOAT/REAL (which is the original sin the whole article exists to prevent):

CREATE TABLE fee_schedules (
  version        TEXT PRIMARY KEY,
  effective_from DATE   NOT NULL,
  body           JSONB  NOT NULL     -- {class: {amount_cents, tax_group}}
);

CREATE TABLE quotes (
  quote_id         UUID PRIMARY KEY,
  current_revision INT  NOT NULL DEFAULT 0,
  status           TEXT NOT NULL CHECK (status IN
                     ('draft','issued','accepted','superseded','expired'))
);
-- quotes is a THIN pointer; all substance lives in quote_events.
-- Rebuilding `quotes` from the event log must always be possible.

And the TypeScript view of a materialized line, the shape the counter UI renders:

interface RenderedLine {
  description: string;
  unitCents: Cents; qty: number;
  extensionCents: Cents;      // exact product
  feeClass?: FeeClass;        // levy attaches per unit if present
  taxGroup: "gst" | "exempt";
}

Three deliberate omissions, each a design statement. There is no discount_percent column on any persistent line — percentages exist only inside adjustment events, computed to cents at application time. There is no total column on quotes — totals live on events, where they were computed, with the versions that computed them. And there is no nullable tax_rate defaulting to "current" — rates are always explicit arguments, because a default that tracks the present is a time bomb for the past.

Where the design meets the driveway

Strip away the tire-and-levy particulars and the design is five commitments, each small, each load-bearing:

Represent money as typed integer cents, with rates as integer basis points, so representation error is impossible rather than managed.
Round in exactly one function, under exactly one written policy, at named sites in a declared calculation order — and version both the policy and the fee data.
Compute quotes with a pure function whose every input is explicit, so any historical figure is reproducible from its recorded inputs.
Record changes as append-only events carrying actor, reason, versions, and the computed result — provenance and checksum in one row.
Make recalculation idempotent at both the math layer (purity) and the transport layer (idempotency keys), so retries and verification sweeps are boring.

None of this is exotic. All of it is the difference between a quoting tool that a one-location tire business could actually trust and a spreadsheet with delusions. The pattern generalizes far past tires — it applies to any system that promises a person a number and expects them to still believe it later — but the grounding matters: constraints like whole-cent totals, per-unit levies, single-rate GST, and quantities of two and four are what make the design tractable enough to get provably right. If the domain itself interests you — what actually distinguishes an all-season from an all-weather compound, or how seasonal changeovers are scheduled around the first snowfall rush, or how a storefront like this Calgary tire operation organizes the services these quotes describe — the operational side has its own depth, from reading a sidewall to decoding load indexes, and even the humble online scheduling flow is downstream of exactly one requirement: the number quoted is the number paid.

One final restatement of the frame, because it belongs at both ends of an article like this: the operational constraints above are real, the illustrative figures are not real prices, and the system is a design on paper — a target worth aiming at, described precisely enough to build, tested in the only way that counts before production exists: by construction.

Two Records, One Driver: Entity Resolution for People and Vehicles in a Service Backend

KMJ Tire Calgary — Wed, 12 Aug 2026 16:22:17 +0000

The Tuesday Where One Driver Became Four Rows

A customer walked in with a set of winter wheels he had stored with us the previous spring. The counter staffer searched his surname, found nothing useful, and created a new customer row. His wheels were in the rack under a tag that referenced a VIN. His spring visit had been entered from a web form under "Jonathan." The autumn visit before that had been entered by phone under "Jon." A fourth row existed because someone had typed his mobile number with the last digit transposed.

Four rows. One person. One vehicle. The storage tag was the only thing that saved us, and the storage tag only worked because a technician had photographed the VIN plate through the windshield eighteen months earlier.

That is entity resolution, and it is not an exotic problem reserved for banks and hospitals. Any operation that accepts identity from humans under time pressure will manufacture duplicates. Ours does roughly fifteen thousand vehicle interactions a year across tire and oil work, which is small enough that people assume the problem does not exist and large enough that it absolutely does. This is a walkthrough of how we model it: what we normalize, how we generate candidates, how we score them, and — the part most write-ups skip — how we undo a bad decision six months later without corrupting history.

Duplicates Are Manufactured, Not Discovered

It helps to stop thinking of duplicates as data-quality accidents and start thinking of them as the predictable output of specific mechanisms. We catalogued ours. Each one needs a different countermeasure, which is why a single "fuzzy match on name" heuristic never works.

Transcription noise under time pressure. During the two-week crunch around a seasonal changeover, intake volume triples and the person entering data is standing, holding a tablet, with three people behind the first. Digit transposition in phone numbers spikes measurably in those weeks. So do truncated surnames.
Provenance divergence. A record born in the self-serve web form has a validated email and a legal-form name. A record born at the counter has a nickname and no email. A record born from a voice conversation has whatever the staffer heard. These three describe the same human and share almost no exact tokens.
Shared household numbers. Two adults, one landline or one mobile listed for both. Phone agreement is strong evidence for a household and weak evidence for a person, and conflating those two is the single most common way a naive matcher fuses a married couple into one entity.
Number recycling. Carriers reissue numbers. A number that identified one customer in 2021 can identify an unrelated person in 2026. Any rule that treats phone equality as identity equality without a temporal guard will eventually merge strangers.
Plate transfer. In Alberta the plate follows the registrant, not the vehicle. Someone sells a car, keeps the plate, puts it on the replacement. Plate is therefore a pointer that gets reassigned, and treating it as a vehicle key silently glues two vehicles' histories together.
VIN captured from a photograph. The dash plate is behind glass at an angle, often dirty, often in a dark bay. Optical character recognition and human eyes both confuse S with 5, B with 8, and 0 with D. One wrong character produces a vehicle that has never existed.
Fleet versus retail confusion. A fleet program account has a dispatcher whose phone appears on forty vehicles. If the dispatcher is modelled as the customer, forty vehicles collapse into one relationship and the per-unit history becomes unusable.
Name variants that are not typos. Diacritics dropped, hyphenated surnames split, given names anglicized, married names adopted mid-history. These are legitimately different strings for the same person, and a strict comparison will never join them.
Deliberate separation. Occasionally a person wants two profiles — a personal vehicle and a business vehicle — and the "duplicate" is intentional. A resolution system with no way to record "these are known to be distinct" will re-merge them every night.

That last one matters more than it seems. Any deduplication pipeline that cannot store a negative assertion will thrash forever.

Identifier Stability Beats Identifier Convenience

Before writing any comparison logic, rank your identifiers by how stable they are over time and how strongly they bind to the thing you care about. Convenience and stability are almost inversely correlated, which is why systems drift toward the wrong keys.

Identifier	Binds to	Stability over time	Availability at intake	Typical corruption	Practical role
VIN (17 char)	The physical vehicle	Permanent for the life of the unit	Poor — often skipped when busy	Single-character misreads from photos or glare	Strongest vehicle anchor; verify the check digit before trusting it
Licence plate	The registrant's entitlement	Low — transferable and reassigned	Excellent, visible on arrival	Ambiguous glyphs, spacing, stale after transfer	Good candidate generator, poor persistent key
Phone (E.164)	A household or a dispatcher	Medium — recycled every few years	Excellent	Transposition, missing area code, extensions	Strong blocking key, medium person evidence
Email	An account, not a person	Medium-high, but frequently absent	Poor for walk-in traffic	Shared family addresses, typo domains	High weight when present, low coverage
Name	A person, loosely	High in essence, low in spelling	Always present	Everything imaginable	Never sufficient alone; useful in combination
Postal code	A residence	Medium	Good	Format variants, stale after moving	Weak corroboration only
Wheel storage tag	A physical set of wheels	High while stored	Internal, always present	Mislabelling at the rack	Excellent internal cross-check

Notice that the two identifiers a staffer can grab fastest — plate and phone — are both pointers rather than identities. That mismatch is the core tension. You need the fast ones to find candidates and the slow ones to confirm them.

Normalize First, Or Everything Downstream Is Noise

Everything that follows assumes a normalization layer that is deterministic, versioned, and stored separately from the raw input. Three properties matter.

Normalization must be pure and reproducible: given the same raw string and the same normalizer version, you get the same output forever. Store the version alongside the output so you can tell which records were processed by which logic. When you fix a bug in surname folding, you need to know exactly which derived values are now stale.

Normalization must never destroy the original. Persist the raw string the human typed. You will need it during a review, and you will need it when a regulator or a customer asks what you actually recorded. The normalized value is a derived index, not a replacement.

Normalization must fail loudly rather than guess. If a phone string cannot be resolved to a valid North American number, record it as unusable with a reason code instead of coercing it into something plausible. Silent coercion is how you end up with three hundred customers whose phone is +10000000000.

E.164 Is The Only Phone Format Worth Persisting

Every phone comparison in the system operates on E.164 strings and nothing else. The normalizer below handles the input shapes we actually see: parenthesized area codes, dotted separators, a leading long-distance 1, trailing extensions, and pasted international strings that begin with the North American escape prefix.

import re
from typing import NamedTuple, Optional


class PhoneResult(NamedTuple):
    e164: Optional[str]
    reason: str


_EXTENSION = re.compile(r"\b(?:ext|extn|x|poste)\.?\s*\d{1,6}\s*$", re.I)
_NON_DIGIT = re.compile(r"[^0-9]")


def normalize_nanp(raw: str) -> PhoneResult:
    """Reduce a North American phone string to E.164, or explain why not."""
    if not raw:
        return PhoneResult(None, "empty")
    text = _EXTENSION.sub("", raw.strip())
    digits = _NON_DIGIT.sub("", text)
    if digits.startswith("011"):
        return PhoneResult(None, "international_escape_prefix")
    if len(digits) == 11 and digits.startswith("1"):
        digits = digits[1:]
    if len(digits) != 10:
        return PhoneResult(None, "wrong_length:{}".format(len(digits)))
    npa, nxx = digits[0:3], digits[3:6]
    if npa[0] in "01" or nxx[0] in "01":
        return PhoneResult(None, "invalid_npa_or_nxx")
    if npa[1] == "1" and npa[2] == "1":
        return PhoneResult(None, "n11_service_code")
    return PhoneResult("+1" + digits, "ok")

Running it over a handful of representative inputs:

'(403) 555-0142'           -> PhoneResult(e164='+14035550142', reason='ok')
'1-403-555-0142'           -> PhoneResult(e164='+14035550142', reason='ok')
'+1 403 555 0142 ext 12'   -> PhoneResult(e164='+14035550142', reason='ok')
'403.555.014'              -> PhoneResult(e164=None, reason='wrong_length:9')
'011 44 20 7946 0000'      -> PhoneResult(e164=None, reason='international_escape_prefix')
'211-555-0142'             -> PhoneResult(e164=None, reason='n11_service_code')

Two deliberate choices. Extensions are stripped rather than preserved in the match key, because an extension identifies a desk inside an organization and two people at the same organization should not fuse. We keep the extension in the raw record and in a separate column; it just does not participate in comparison. And the N11 guard exists because someone will eventually paste a service number into the field. The 555-01xx numbers used throughout this article are from the range reserved for fictional use, which is why they appear in sample data without hesitation.

Implementing The VIN Check Digit Without Getting It Wrong

The VIN is the only identifier in this domain with built-in error detection, and it is astonishing how many systems store VINs without ever using it. North American VINs assigned since 1981 carry a check digit in position nine. Getting the algorithm right is not optional: a subtly wrong implementation is worse than none, because it rejects good data and passes bad data.

Three details trip people up. First, the letters I, O, and Q are excluded from the VIN alphabet entirely, precisely because they are confusable with 1 and 0. Any VIN containing them is malformed, full stop. Second, the transliteration table is not "position in the alphabet" — it wraps, so J maps to 1 and S maps to 2. Third, position nine contributes weight zero to its own sum, and a remainder of 10 is written as the letter X.

VIN_TRANSLITERATION = {
    "A": 1, "B": 2, "C": 3, "D": 4, "E": 5, "F": 6, "G": 7, "H": 8,
    "J": 1, "K": 2, "L": 3, "M": 4, "N": 5, "P": 7, "R": 9,
    "S": 2, "T": 3, "U": 4, "V": 5, "W": 6, "X": 7, "Y": 8, "Z": 9,
}
VIN_WEIGHTS = (8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2)
VIN_ALPHABET = set("0123456789") | set(VIN_TRANSLITERATION)


class VinError(ValueError):
    pass


def vin_check_digit(vin: str) -> str:
    """Return the character that belongs in position 9 of a 17-character VIN."""
    vin = (vin or "").strip().upper()
    if len(vin) != 17:
        raise VinError("length {} is not 17".format(len(vin)))
    total = 0
    for position, ch in enumerate(vin):
        if ch not in VIN_ALPHABET:
            raise VinError("character {!r} is illegal at position {}".format(ch, position + 1))
        value = int(ch) if ch.isdigit() else VIN_TRANSLITERATION[ch]
        total += value * VIN_WEIGHTS[position]
    remainder = total % 11
    return "X" if remainder == 10 else str(remainder)


def vin_is_valid(vin: str) -> bool:
    try:
        return vin_check_digit(vin) == vin.strip().upper()[8]
    except VinError:
        return False

Exercising it against a synthetic VIN — ZZZ is not an assigned world manufacturer identifier, so this string cannot collide with a real vehicle — plus the widely published test vector 1M8GDM9AXKP042788, whose check digit is X:

check digit of ZZZTESTV9N9SB4207 is 9 | valid: True
S read as 5: False
B read as 8: False
digits swapped: False
illegal letter Q: False
known reference 1M8GDM9AXKP042788 -> X

Every one of those failure cases is a real transcription error we have seen when a VIN is keyed in from a photograph taken through a windshield.

What The Check Digit Cannot Save You From

Modulo-11 with those weights catches all single-character substitutions and all transpositions of adjacent characters. It does not catch everything. Roughly one in eleven random 17-character strings will pass by coincidence, so validity is evidence, not proof. More importantly, a VIN can be perfectly valid and still be the wrong vehicle — someone reads the VIN off the paperwork of the car parked in the next bay, or a fleet coordinator pastes the wrong row from a spreadsheet.

So we treat check-digit validity as a gate on storage confidence, not on truth. A VIN that fails validation is retained in the raw record, flagged, and excluded from blocking and scoring. A VIN that passes gets a confidence tier based on how it was captured: scanned barcode outranks manual entry, which outranks a value derived from a photograph. When two records disagree on a valid VIN, that disagreement is a hard veto rather than a negative weight, because a confirmed VIN conflict means you are looking at two different vehicles regardless of how much else matches.

There is also a population wrinkle worth knowing. Vehicles built before the 1981 standardization, some imported units, and a scattering of trailers and equipment carry VINs that are shorter than 17 characters or that do not follow the check-digit convention at all. If you serve any commercial customers, you will meet these. Model the field as "vehicle identifier with a scheme tag" rather than "17-character VIN," and your data layer stops lying to you.

Plates Are Leases, Not Primary Keys

Plate handling needs two different canonical forms, and conflating them causes a specific class of bug.

The comparison form strips whitespace and punctuation and uppercases. Nothing more. BXK 4471 and bxk-4471 are the same plate; BXK4471 and 8XK4471 are not, because on a real plate the glyphs are distinct and the registry issued exactly one of them.

The blocking form is deliberately lossier. It folds visually confusable glyph pairs together so that a mis-keyed plate still lands in the same bucket as the correct one. This form exists only to generate candidates. It must never be used to decide anything.

import re
import unicodedata

NAME_SUFFIXES = {"jr", "sr", "ii", "iii", "iv"}
_NAME_JUNK = re.compile(r"[^a-z ]+")
_PLATE_JUNK = re.compile(r"[^A-Z0-9]+")
_GLYPH_FOLD = str.maketrans({"O": "0", "Q": "0", "I": "1", "S": "5", "B": "8", "Z": "2"})


def canonical_plate(raw: str) -> str:
    """Exact-comparison form: case and separators removed, glyphs preserved."""
    return _PLATE_JUNK.sub("", (raw or "").upper())


def plate_block_key(raw: str) -> str:
    """Recall-oriented form: confusable glyphs collapsed. Candidates only."""
    return canonical_plate(raw).translate(_GLYPH_FOLD)


def fold_name(raw: str) -> str:
    if not raw:
        return ""
    decomposed = unicodedata.normalize("NFKD", raw)
    ascii_only = "".join(c for c in decomposed if not unicodedata.combining(c))
    lowered = ascii_only.lower().replace("-", " ").replace("'", "")
    parts = [p for p in _NAME_JUNK.sub(" ", lowered).split() if p not in NAME_SUFFIXES]
    return " ".join(parts)


_SOUNDEX = {}
for group, code in (("bfpv", "1"), ("cgjkqsxz", "2"), ("dt", "3"),
                    ("l", "4"), ("mn", "5"), ("r", "6")):
    for letter in group:
        _SOUNDEX[letter] = code


def soundex(word: str) -> str:
    word = fold_name(word).replace(" ", "")
    if not word:
        return ""
    out = word[0].upper()
    previous = _SOUNDEX.get(word[0], "")
    for ch in word[1:]:
        code = _SOUNDEX.get(ch, "")
        if code and code != previous:
            out += code
        if ch not in "hw":
            previous = code
        if len(out) == 4:
            break
    return (out + "000")[:4]

Beyond canonicalization, plates need a validity window. We store plate observations as time-bounded facts attached to a vehicle, not as a column on the vehicle row. When a customer arrives with a plate that we last saw on a different VIN, that is not a data error to reconcile — it is a transfer event to record. Losing that distinction is how a returning customer's wheel balancing history from a sold vehicle ends up attached to the car they bought last month.

Folding Names Without Flattening People

Name folding is the step where enthusiasm does the most damage. Aggressive folding boosts recall and destroys precision, and in a small population the precision loss is what people notice, because merging two real customers is visible and embarrassing while missing a duplicate is merely inefficient.

Our folding does four things and stops: Unicode decomposition with combining marks removed, lowercasing, hyphen and apostrophe normalization to spaces or nothing, and removal of generational suffixes. D'Angelo-Rossi, Jr becomes dangelo rossi. We do not stem, we do not apply nickname dictionaries at the folding stage, and we do not reorder tokens.

Nickname expansion happens later, as a scoring signal rather than a normalization step, and it is directional. "Jon" being a prefix of "Jonathan" earns partial credit. A curated table maps "Bill" toward "William" and "Sasha" toward "Alexander" — but as evidence with a weight, never as a rewrite. The moment you rewrite the stored value, you have lost the ability to tell a reviewer why the system thought two records matched.

Soundex is the phonetic key we use for blocking. It is old, crude, and heavily biased toward English orthography, which is a genuine weakness in a city as linguistically varied as this one. Its saving grace is that it is cheap and its failure mode is predictable: it over-groups, which is exactly what you want from a candidate generator. Okonkwo and Okonquo both fold to O252. It is not doing the deciding.

Candidate Generation, Or How To Avoid n² Comparisons

With a hundred thousand source records, all-pairs comparison is five billion evaluations. Even at a microsecond each that is over an hour of CPU for a nightly job, and the comparison function is not going to be a microsecond. Blocking is the standard escape: emit one or more keys per record, and only compare records that share a key.

The tradeoff is explicit. A narrow key produces small blocks and fast runs but misses pairs whose linking evidence lives in a field the key ignores. A broad key produces high recall and blocks large enough to reintroduce the quadratic problem inside a single bucket. The answer is several independent narrow keys rather than one clever broad one, with a hard size cap that skips pathological blocks and reports them.

def blocking_keys(rec: dict) -> set:
    keys = set()
    vin = (rec.get("vin") or "").upper()
    if len(vin) == 17:
        keys.add("vin8:" + vin[-8:])
        keys.add("vin6:" + vin[-6:])
    plate = plate_block_key(rec.get("plate"))
    if len(plate) >= 5:
        keys.add("plt:" + plate)
    phone = rec.get("phone_e164") or ""
    if len(phone) == 12:
        keys.add("ph7:" + phone[-7:])
    surname_key = soundex(rec.get("surname"))
    given = fold_name(rec.get("given_name"))
    if surname_key:
        if given:
            keys.add("nm:{}{}".format(surname_key, given[0]))
        if len(phone) == 12:
            keys.add("nmph:{}{}".format(surname_key, phone[-4:]))
        fsa = (rec.get("postal") or "").upper().replace(" ", "")[:3]
        if len(fsa) == 3:
            keys.add("nmfsa:{}{}".format(surname_key, fsa))
    return keys


MAX_BLOCK_SIZE = 60


def candidate_pairs(records):
    from collections import defaultdict
    index = defaultdict(list)
    for rec in records:
        for key in blocking_keys(rec):
            index[key].append(rec["id"])
    pairs, skipped = set(), []
    for key, ids in index.items():
        if len(ids) < 2:
            continue
        if len(ids) > MAX_BLOCK_SIZE:
            skipped.append((key, len(ids)))
            continue
        for i in range(len(ids)):
            for j in range(i + 1, len(ids)):
                pairs.add(tuple(sorted((ids[i], ids[j]))))
    return pairs, skipped

Here is the synthetic fixture used for the rest of this article. Invented people, invented plates, one synthetic VIN.

# synthetic sample data: invented people, invented plates, synthetic VIN
SAMPLE = [
    {"id": "r1", "given_name": "Jonathan", "surname": "Okonkwo", "phone_e164": "+14035550142",
     "plate": "BXK4471", "vin": "ZZZTESTV9N9SB4207", "postal": "T2N 1N4", "origin": "web_form"},
    {"id": "r2", "given_name": "Jon", "surname": "Okonkwo", "phone_e164": "+14035550142",
     "plate": "bxk 4471", "vin": "", "postal": "T2N1N4", "origin": "front_counter"},
    {"id": "r3", "given_name": "Marie", "surname": "Okonkwo", "phone_e164": "+14035550142",
     "plate": "DHR2210", "vin": "", "postal": "T2N1N4", "origin": "front_counter"},
    {"id": "r4", "given_name": "Jonathan", "surname": "Okonkwo", "phone_e164": "+14035550143",
     "plate": "", "vin": "", "postal": "T2N1N4", "origin": "voice_intake"},
    {"id": "r5", "given_name": "Jonathan", "surname": "Okonkwo", "phone_e164": "",
     "plate": "", "vin": "ZZZTESTV9N9SB4207", "postal": "", "origin": "storage_tag"},
]

Picking Block Keys That Recall Without Exploding

The MAX_BLOCK_SIZE cap deserves a paragraph of its own, because it is where blocking meets reality. A key like "soundex of surname plus first initial" behaves beautifully for O252j and catastrophically for the local equivalent of S530j. One oversized bucket can dominate an entire run.

We cap at sixty and emit skipped keys to a metric rather than silently dropping them. If a key is skipped, the pairs inside it were never evaluated, and pretending otherwise makes your recall measurement a fiction. In practice the skipped list is short and dominated by two things: the surname keys for very common names, and the phone key belonging to a dispatcher whose number is attached to an entire commercial vehicle fleet. The second case gets handled structurally rather than by tuning — dispatcher numbers are tagged as organizational and excluded from person-level blocking entirely.

Two more habits earn their keep. Suffix keys beat prefix keys for VINs, because the last eight characters are the sequential serial and carry far more entropy than the manufacturer prefix; blocking on the first eight would put every vehicle from one marque in one bucket. And compound keys beat single-field keys when both components are individually weak: surname phonetic plus last four digits of phone is far more selective than either half, and it survives an area-code error that a full-phone key would not.

Running the generator over the fixture yields nine candidate pairs from five records — a reminder that even tiny populations produce a lot of comparisons once several keys are in play.

Weighting Field Agreement With Numbers You Can Defend

Once you have pairs, you need a score. The Fellegi–Sunter framework is fifty years old and still the right starting point because it forces you to state two probabilities per field and then does the arithmetic honestly.

For each field you estimate m, the probability that the field agrees given the pair is genuinely the same entity, and u, the probability that it agrees given the pair is not. Agreement contributes log2(m/u) bits; disagreement contributes log2((1-m)/(1-u)), which is negative. Missing data contributes zero, which is the property that makes this approach so much better than an ad-hoc percentage: an absent VIN neither helps nor hurts.

import math
from dataclasses import dataclass


@dataclass(frozen=True)
class FieldModel:
    m: float   # P(field agrees | same entity)
    u: float   # P(field agrees | different entities)

    @property
    def agree_weight(self) -> float:
        return math.log2(self.m / self.u)

    @property
    def disagree_weight(self) -> float:
        return math.log2((1.0 - self.m) / (1.0 - self.u))


MODELS = {
    "vin":       FieldModel(m=0.94, u=0.0000005),
    "plate":     FieldModel(m=0.88, u=0.0000020),
    "household": FieldModel(m=0.90, u=0.0035000),
    "surname":   FieldModel(m=0.92, u=0.0030000),
    "given":     FieldModel(m=0.85, u=0.0120000),
    "email":     FieldModel(m=0.55, u=0.0002000),
}
PARTIAL_CREDIT = 0.35


def weight_for(field: str, level: str) -> float:
    model = MODELS[field]
    if level == "agree":
        return model.agree_weight
    if level == "partial":
        return model.agree_weight * PARTIAL_CREDIT
    if level == "disagree":
        return model.disagree_weight
    return 0.0

Which produces this weight table:

vin        agree +20.84  disagree  -4.06
plate      agree +18.75  disagree  -3.06
household  agree  +8.01  disagree  -3.32
surname    agree  +8.26  disagree  -3.64
given      agree  +6.15  disagree  -2.72
email      agree +11.43  disagree  -1.15

Where do the numbers come from? The u values are estimated from the data itself: sample random pairs from your population, measure how often each field agrees by chance, and use that frequency. For VIN the chance-agreement rate is essentially the reciprocal of the distinct-VIN count, hence the tiny value and the enormous weight. The m values are harder and require a labelled sample; start with a defensible guess, then refine against clerical review outcomes. Expectation-maximization can estimate both without labels, but on a population this size the estimates are unstable and I would rather label eight hundred pairs by hand and know what I have.

One refinement that matters: u should be frequency-adjusted for the specific value, not just the field. Agreement on a surname held by 0.4% of your customers is far weaker evidence than agreement on one held by 0.004%. The full treatment computes per-value weights; a cheap approximation is to halve the surname weight whenever the folded value appears in the top fifty most frequent surnames in your own table.

Conditional Independence Is A Lie In A Household

The naive Fellegi–Sunter sum assumes fields are conditionally independent given match status. Phone and postal code are not remotely independent — people who share an address usually share a phone. Summing both as separate evidence double-counts the same underlying fact and inflates scores for exactly the pairs you most need to keep apart: family members.

The pragmatic fix is to collapse correlated fields into a single composite comparison. Our household field takes phone agreement if both phones exist, and falls back to forward sortation area agreement otherwise, capped at partial credit. One field, one weight, no double counting.

def compare_levels(left: dict, right: dict):
    lv, rv = (left.get("vin") or "").upper(), (right.get("vin") or "").upper()
    if len(lv) == 17 and len(rv) == 17:
        yield "vin", "agree" if lv == rv else ("partial" if levenshtein(lv, rv) <= 2 else "disagree")
    else:
        yield "vin", "unknown"

    lp, rp = canonical_plate(left.get("plate")), canonical_plate(right.get("plate"))
    yield "plate", ("agree" if lp == rp else "disagree") if lp and rp else "unknown"

    lph, rph = left.get("phone_e164") or "", right.get("phone_e164") or ""
    lfsa = (left.get("postal") or "").upper().replace(" ", "")[:3]
    rfsa = (right.get("postal") or "").upper().replace(" ", "")[:3]
    if lph and rph:
        if lph == rph:
            yield "household", "agree"
        elif levenshtein(lph, rph) == 1:
            yield "household", "partial"
        else:
            yield "household", "disagree"
    elif lfsa and rfsa:
        yield "household", "partial" if lfsa == rfsa else "disagree"
    else:
        yield "household", "unknown"

    ls, rs = fold_name(left.get("surname")), fold_name(right.get("surname"))
    if ls and rs:
        near = soundex(ls) == soundex(rs) or edit_ratio(ls, rs) >= 0.80
        yield "surname", "agree" if ls == rs else ("partial" if near else "disagree")
    else:
        yield "surname", "unknown"

    lg, rg = fold_name(left.get("given_name")), fold_name(right.get("given_name"))
    if lg and rg:
        clipped = lg.startswith(rg) or rg.startswith(lg)
        yield "given", "agree" if lg == rg else ("partial" if clipped or edit_ratio(lg, rg) >= 0.75 else "disagree")
    else:
        yield "given", "unknown"

    le, rr = (left.get("email") or "").strip().lower(), (right.get("email") or "").strip().lower()
    yield "email", ("agree" if le == rr else "disagree") if le and rr else "unknown"

The two string helpers it leans on are the ordinary dynamic-programming edit distance and its length-normalized complement:

def levenshtein(a: str, b: str) -> int:
    if a == b:
        return 0
    if not a or not b:
        return len(a) + len(b)
    previous = list(range(len(b) + 1))
    for i, ca in enumerate(a, 1):
        current = [i]
        for j, cb in enumerate(b, 1):
            current.append(min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (ca != cb)))
        previous = current
    return previous[-1]


def edit_ratio(a: str, b: str) -> float:
    if not a or not b:
        return 0.0
    return 1.0 - levenshtein(a, b) / max(len(a), len(b))

Note that a phone one edit away earns partial credit rather than full — that is the transposition case from intake — while a phone two or more edits away scores as disagreement. The same distance powers the near-miss VIN level, where two characters of slack absorbs a photograph misread without accepting an unrelated unit. Anything looser and you start joining vehicles that differ only in trim code, which the tire fitment catalogue will happily tell you are genuinely different machines.

A Worked Comparison, Bit By Bit

Take r1 (web form, full given name, plate and VIN present) against r3 (counter entry, different given name, same household phone, different plate). Field by field:

vin: one side is empty, so unknown → 0.00
plate: BXK4471 versus DHR2210, disagree → −3.06
household: identical E.164 strings, agree → +8.01
surname: both fold to okonkwo, agree → +8.26
given: jonathan versus marie, neither prefix nor near, disagree → −2.72
email: absent on both sides, unknown → 0.00

Total: 10.49 bits. With an auto-link threshold of 12.0, that lands in the review band — which is the correct answer. These two records probably describe two adults in one household. Without the composite household field, phone and postal would have contributed separately and the pair would have crossed the threshold and merged a couple.

Contrast with r1 against r5, the wheel-storage tag that carries a VIN and a name but no phone or address. VIN agrees (+20.84), surname agrees (+8.26), given name agrees (+6.15), everything else unknown. Total 35.25 bits, comfortably a link, driven almost entirely by one strong identifier. That asymmetry is the whole point: a single high-quality field beats a pile of weak corroboration.

Deterministic Vetoes Over Probabilistic Enthusiasm

Probabilistic scoring is the right default, but there are facts about this domain that no weight should be allowed to outvote. Those go in a veto layer that runs after scoring and can only demote a decision, never promote one.

AUTO_LINK_AT = 12.0
REVIEW_FLOOR_AT = 3.0


def hard_block_reason(levels: dict) -> Optional[str]:
    vehicle_anchor = levels["vin"] == "agree" or levels["plate"] == "agree"
    if levels["vin"] == "disagree":
        return "vin_conflict"
    if levels["given"] == "disagree" and not vehicle_anchor:
        return "given_name_conflict_without_vehicle_anchor"
    return None


def decide(left: dict, right: dict):
    rows = [(f, lvl, weight_for(f, lvl)) for f, lvl in compare_levels(left, right)]
    total = sum(w for _, _, w in rows)
    levels = {f: lvl for f, lvl, _ in rows}
    reason = hard_block_reason(levels)
    if total >= AUTO_LINK_AT:
        verdict = "review" if reason else "link"
    elif total >= REVIEW_FLOOR_AT:
        verdict = "review"
    else:
        verdict = "distinct"
    return {"score": round(total, 2), "verdict": verdict, "veto": reason, "rows": rows}

Full run over the fixture:

r1~r2   37.17 link     -
        vin=unknown plate=agree household=agree surname=agree given=partial email=unknown
r1~r3   10.49 review   given_name_conflict_without_vehicle_anchor
        vin=unknown plate=disagree household=agree surname=agree given=disagree email=unknown
r1~r4   17.21 link     -
        vin=unknown plate=unknown household=partial surname=agree given=agree email=unknown
r1~r5   35.25 link     -
        vin=agree plate=unknown household=unknown surname=agree given=agree email=unknown
r3~r4    8.34 review   given_name_conflict_without_vehicle_anchor
        vin=unknown plate=unknown household=partial surname=agree given=disagree email=unknown

When does each approach win? Here is the honest division of labour:

Situation	Deterministic rule	Probabilistic score
A verified strong identifier agrees exactly	Wins — cheap, explainable, no tuning	Redundant
A verified strong identifier conflicts	Wins as a veto	Dangerous; weights can be outvoted
Several weak fields partially agree	Cannot express degree	Wins clearly
Regulatory or policy constraint	Wins — must be auditable	Unacceptable
Novel error pattern nobody anticipated	Fails silently	Degrades gracefully into review
Explaining a decision to a customer	Wins — one sentence	Needs a rendered weight breakdown

Our production pipeline is deterministic first, probabilistic second, veto third. Exact agreement on a validated VIN links immediately without scoring. Everything else goes through weights. Vetoes then pull suspicious links down into review.

The Review Band Is Deliberate Engineering

The gap between REVIEW_FLOOR_AT and AUTO_LINK_AT is not an admission that the model is weak. It is a budget. Fellegi–Sunter's original formulation sets the two thresholds from your tolerated false-match and false-non-match rates, and everything in between is routed to a human. Widen the band and you buy accuracy with labour; narrow it and you buy throughput with errors.

Sizing it is an operations question, not a statistics question. We measured how many pairs land in the band per week and set the thresholds so that the queue stays under what one person can clear in twenty minutes a day, with headroom for the changeover crunch when volume triples. If the queue grows faster than it drains, the band is wrong or the upstream capture is degrading; either way it is a signal, not a chore.

The review interface matters more than the model. A reviewer needs the raw values side by side — not the normalized ones — the per-field weight breakdown, the provenance of each record, and the service history of both. Three outcomes are available: link, distinct, or defer with a note. "Distinct" writes a negative assertion that suppresses the pair permanently, which is what stops the nightly job from re-proposing the same married couple every week for a year.

Persist Links, Never Overwrite Rows

Here is the structural decision that separates systems you can live with from systems you cannot: never destructively merge. Keep every source record exactly as captured, immutable, and express identity as a separate layer of assertions on top.

-- Immutable capture. One row per identity assertion made by a human or an import.
CREATE TABLE source_record (
    source_record_id   uuid PRIMARY KEY,
    origin             text NOT NULL,          -- web_form | front_counter | voice_intake | fleet_import | storage_tag
    captured_at        timestamptz NOT NULL,
    location_id        int NOT NULL,
    raw_payload        jsonb NOT NULL,         -- exactly what was typed, never edited
    normalizer_version int,
    given_name_folded  text,
    surname_folded     text,
    surname_phonetic   text,
    phone_e164         text,
    phone_reject_code  text,
    email_normalized   text,
    plate_canonical    text,
    vin_upper          char(17),
    vin_check_ok       boolean,
    postal_fsa         char(3)
);

CREATE INDEX source_record_phone_idx ON source_record (phone_e164) WHERE phone_e164 IS NOT NULL;
CREATE INDEX source_record_vin_idx   ON source_record (vin_upper)  WHERE vin_check_ok;
CREATE INDEX source_record_plate_idx ON source_record (plate_canonical);

-- Pairwise assertions. Positive and negative, both first class.
CREATE TABLE identity_link (
    identity_link_id  bigserial PRIMARY KEY,
    entity_kind       text NOT NULL CHECK (entity_kind IN ('person', 'vehicle')),
    left_record_id    uuid NOT NULL,
    right_record_id   uuid NOT NULL,
    assertion         text NOT NULL CHECK (assertion IN ('same', 'distinct')),
    score_bits        numeric(6,2),
    veto_reason       text,
    decided_by        text NOT NULL,          -- 'auto:v7' or a staff identifier
    decided_at        timestamptz NOT NULL DEFAULT now(),
    retired_at        timestamptz,
    retired_reason    text,
    CHECK (left_record_id < right_record_id),
    FOREIGN KEY (left_record_id)  REFERENCES source_record,
    FOREIGN KEY (right_record_id) REFERENCES source_record
);

CREATE UNIQUE INDEX identity_link_live_idx
    ON identity_link (entity_kind, left_record_id, right_record_id)
    WHERE retired_at IS NULL;

-- Materialized closure. Cheap to rebuild, never a source of truth.
CREATE TABLE identity_cluster (
    cluster_id     uuid PRIMARY KEY,
    entity_kind    text NOT NULL,
    generation     int NOT NULL,
    computed_at    timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE cluster_member (
    cluster_id       uuid NOT NULL REFERENCES identity_cluster,
    source_record_id uuid NOT NULL REFERENCES source_record,
    PRIMARY KEY (cluster_id, source_record_id)
);

Three properties fall out of this shape. The raw capture is never mutated, so an audit can always reconstruct what a human actually entered. Identity is a set of retractable assertions, so reversing a decision means retiring a row rather than reconstructing deleted data. And the cluster table is derived, disposable, and versioned by generation, so you can rebuild the whole closure after a weight change and diff the result before promoting it.

The CHECK (left_record_id < right_record_id) constraint plus the partial unique index means one live assertion per unordered pair, enforced by the database rather than by hope.

Materializing Clusters With Union-Find

Turning pairwise assertions into groups is a connected-components problem, and disjoint-set union is the obvious tool. You will write this whether you plan to or not, so write it well.

class DisjointSet:
    def __init__(self):
        self.parent = {}
        self.rank = {}

    def add(self, item):
        self.parent.setdefault(item, item)
        self.rank.setdefault(item, 0)

    def find(self, item):
        self.add(item)
        root = item
        while self.parent[root] != root:
            root = self.parent[root]
        while self.parent[item] != root:          # path compression
            self.parent[item], item = root, self.parent[item]
        return root

    def union(self, a, b):
        ra, rb = self.find(a), self.find(b)
        if ra == rb:
            return False
        if self.rank[ra] < self.rank[rb]:
            ra, rb = rb, ra
        self.parent[rb] = ra
        if self.rank[ra] == self.rank[rb]:
            self.rank[ra] += 1
        return True


def build_clusters(record_ids, active_links):
    dsu = DisjointSet()
    for rid in record_ids:
        dsu.add(rid)
    for left, right in active_links:
        dsu.union(left, right)
    groups = {}
    for rid in record_ids:
        groups.setdefault(dsu.find(rid), []).append(rid)
    return sorted(sorted(v) for v in groups.values())

Feeding it the three auto-links from the fixture gives [['r1', 'r2', 'r4', 'r5'], ['r3']].

Transitive closure is where entity resolution goes wrong at scale. Union is unconditional: if A links to B and B links to C, then A, B, and C are one cluster even if A and C are wildly dissimilar. One bad link can chain two large groups together, and the failure is invisible until someone notices a customer with forty vehicles.

Two guards are worth the effort. First, run a post-closure sanity pass: for every cluster above a size threshold, evaluate the lowest-scoring internal pair and flag the cluster if that score falls below the review floor. That catches chains held together by a single weak edge. Second, respect negative assertions during closure — if any pair inside a proposed cluster carries a live distinct assertion, refuse the merge and route the whole component to review rather than silently overriding a human.

Unmerge Is A First-Class Operation

You will merge two people wrongly. Plan the reversal before you ship the merge.

Because assertions are retractable and source records are immutable, unmerge is mechanically simple: retire the offending identity_link row with a reason, bump the generation, recompute the closure for the affected component. The cluster splits. No data was destroyed, so nothing needs reconstructing.

What is not simple is everything downstream that captured the merged identity. Consider the artifacts a service visit produces: a work order, an invoice, a wheel-storage tag, a tire-and-rim inspection note, a communication log. If those reference cluster_id directly, an unmerge orphans them or silently reassigns them.

The rule we settled on: transactional records reference source_record_id, never cluster_id. The cluster is a read-time lens, resolved through cluster_member at query time or through a materialized view refreshed after each generation. Any record that must survive an identity change — anything with legal, financial, or safety weight — points at immutable capture. A generated invoice is a document; it names whoever it named when it was issued, and it does not retroactively change owners because a clustering job changed its mind.

External systems need a separate escape hatch. Anything you have already exported — an accounting ledger, a message log, a warranty registration filed with a manufacturer — cannot be unmerged by you. Log every identity change as an event with before and after cluster identifiers so that downstream consumers can reconcile at their own pace. We keep that event stream for seven years, which matches the retention on the financial records it explains.

Ownership Has A Start Date And An End Date

Here is the modelling error I see most often: a vehicle table with an owner_id column. That column asserts a fact with no time bounds, and vehicle ownership is one of the most reliably temporary relationships in this domain. Cars get sold. Fleets rotate units between drivers. A leased truck returns to the lessor.

The relationship needs its own table with validity intervals.

CREATE TABLE vehicle (
    vehicle_id       uuid PRIMARY KEY,
    identifier_scheme text NOT NULL CHECK (identifier_scheme IN ('vin17', 'pre1981', 'serial', 'internal')),
    vin_upper        char(17),
    first_seen_at    timestamptz NOT NULL,
    UNIQUE (identifier_scheme, vin_upper)
);

CREATE TABLE vehicle_custody (
    custody_id     bigserial PRIMARY KEY,
    vehicle_id     uuid NOT NULL REFERENCES vehicle,
    person_cluster uuid NOT NULL,
    valid_period   tstzrange NOT NULL,
    evidence       text NOT NULL,     -- observed_at_visit | stated_by_customer | fleet_roster_import
    EXCLUDE USING gist (vehicle_id WITH =, valid_period WITH &&)
);

CREATE TABLE plate_observation (
    observation_id  bigserial PRIMARY KEY,
    vehicle_id      uuid NOT NULL REFERENCES vehicle,
    plate_canonical text NOT NULL,
    observed_at     timestamptz NOT NULL,
    observed_by     text NOT NULL
);

The EXCLUDE USING gist constraint is the important line. It makes overlapping custody intervals for one vehicle physically impossible at the storage layer, which means the "two owners at once" bug cannot be introduced by an application bug, a race, or a careless backfill.

Plate observations are events, not state. The current plate for a vehicle is the most recent observation; the plate history is the full series. When the same canonical plate appears against a second vehicle_id, the system emits a transfer candidate rather than a conflict, and a reviewer decides whether it was a genuine transfer, a typo, or a vehicle record that was created twice.

Reading Service History Through A Temporal Lens

Once custody is temporal, history questions split into two genuinely different queries, and conflating them produces answers that feel wrong to everybody.

"What has been done to this vehicle?" is a question about the machine. It spans owners. If a set of all-weather tires was fitted two owners ago, that is still the tread on the vehicle today and still relevant when the current driver arrives. The same holds for an all-season fitment with three winters on it, or a spare that was never rotated in.

"What has this person had done?" is a question about the human, and it spans vehicles. It should include only the intervals during which they actually held each vehicle.

-- Everything ever done to one vehicle, annotated with who held it at the time.
SELECT v.visit_id,
       v.performed_at,
       v.service_kind,
       c.person_cluster AS holder_at_time
FROM   service_visit v
JOIN   vehicle_custody c
  ON   c.vehicle_id = v.vehicle_id
 AND   c.valid_period @> v.performed_at
WHERE  v.vehicle_id = $1
ORDER  BY v.performed_at DESC;

-- Everything one person had done, across every vehicle they actually held.
SELECT v.visit_id,
       v.performed_at,
       v.service_kind,
       veh.vin_upper
FROM   service_visit v
JOIN   vehicle_custody c
  ON   c.vehicle_id = v.vehicle_id
 AND   c.valid_period @> v.performed_at
JOIN   vehicle veh ON veh.vehicle_id = v.vehicle_id
WHERE  c.person_cluster = $1
ORDER  BY v.performed_at DESC;

The service_kind enum is deliberately narrow, because our work is narrow: tire_installation, seasonal_changeover, rotation, wheel_balance, flat_repair, tpms_service, wheel_storage_in, wheel_storage_out, oil_change. Nine values, all of them things we actually do. A constrained enum is also a quiet integrity check — if a row shows up that does not fit, something upstream is wrong.

There is a third question the temporal model answers well: "is the tread on this vehicle ours, and how old is it?" That drives a genuinely useful prompt when a vehicle arrives for a puncture repair on rubber we fitted four winters ago, and it only works if the fitment event stayed attached to the vehicle across an ownership change.

Fleet Records Violate Every Retail Assumption

Retail intuitions collapse on the commercial side, and they collapse in ways that are worth enumerating because each one breaks a different part of the pipeline.

The phone number belongs to a dispatcher, not a driver, and appears on every unit. Any person-level rule keyed on phone will fuse the entire roster. We tag organizational numbers explicitly and exclude them from person blocking and from the household comparison entirely.

The name attached to a visit is the driver on shift, which changes weekly. Driver names are attributes of the visit, not identity evidence about the account holder. Feeding them into person resolution generates noise proportional to staff turnover.

Vehicles arrive in batches from a roster import, so provenance is a spreadsheet rather than a human at the counter. Roster imports have their own failure mode: duplicated rows, VINs with a stray leading apostrophe from a spreadsheet export, and units that were sold months ago but never removed. We validate check digits on import and quarantine the failures rather than creating vehicles.

Custody is organizational and the individual driver is irrelevant to it. The person_cluster on a fleet vehicle points at an organization entity, and the driver appears only on the visit. This is also why mobile service visits need the vehicle anchor to be rock solid — there is often nobody present who can confirm anything about the account, just a unit number stencilled on a door.

Finally, unit numbers are a fleet's own internal identifier and they are frequently more reliable in practice than anything else available, because the fleet manager maintains them. Treat a customer-supplied internal identifier as a first-class alias with a namespace: fleet:acme-hauling:unit-114. Namespaced aliases are exact-match evidence with a very small u, which makes them powerful and safe.

Retention, Consent, And The Cost Of Remembering

Identity resolution is a system for remembering people harder than they expect, which puts it squarely inside privacy obligations rather than adjacent to them.

Under Canadian private-sector privacy law the relevant principle is purpose limitation: you collect and retain personal information for identified purposes and no longer than needed to fulfil them. Linking records to avoid duplicate profiles is a defensible purpose — it directly serves service quality and safety. Retaining a decade of phone numbers to build behavioural profiles is a different purpose, and you should not quietly acquire it just because your schema makes it possible.

Practical consequences we implemented. Reason codes on every retention decision, so a stored value can always explain why it is still there. Automatic expiry of unusable capture artifacts: a rejected phone string with a wrong_length code has no ongoing value and is purged after ninety days. Separation of identity data from marketing consent, so that resolving two records into one person never silently transfers a communication preference — consent attaches to the channel and the assertion, not to the cluster.

Deletion is where immutability gets interesting. "Source records are never mutated" cannot mean "we ignore erasure requests." The resolution is tombstoning: the row survives with its identifiers replaced by a redaction marker, the cluster membership survives, and the aggregate history survives in a form that no longer identifies anyone. You lose the ability to re-resolve that record later, which is the correct tradeoff.

One more thing worth stating plainly: every merge you make increases the blast radius of a breach, because a resolved cluster is a richer profile than any of its parts. That is not an argument against resolution. It is an argument for encrypting identifier columns at rest, restricting the review interface to named staff, and logging every access to a cluster view.

Precision, Recall, And The Size Of The Queue

You cannot tune what you do not measure, and "the duplicates seem better" is not a measurement.

Build a labelled sample. Draw a few hundred candidate pairs stratified across the score range — deliberately oversampling near the thresholds, because that is where the decision boundary lives — and have someone adjudicate each one with all available evidence. Several hundred labels is enough to estimate precision and recall with useful confidence at this population size, and it is a day of work, not a project.

From that sample: precision is the fraction of auto-linked pairs that were genuinely the same entity, and recall is the fraction of genuine matches the system linked without human help. Both matter, and they trade off against each other along the threshold. Report them together with the threshold values, always, because a precision number without its operating point is meaningless.

Beyond the pair-level metrics, four population-level indicators earn dashboard space.

-- Duplicate rate: clusters holding more than one source record, by capture channel.
SELECT sr.origin,
       count(*) FILTER (WHERE sizes.n > 1)::numeric / nullif(count(*), 0) AS multi_record_rate,
       avg(sizes.n) AS mean_cluster_size
FROM   cluster_member cm
JOIN   source_record sr ON sr.source_record_id = cm.source_record_id
JOIN   (SELECT cluster_id, count(*) AS n FROM cluster_member GROUP BY 1) sizes
  ON   sizes.cluster_id = cm.cluster_id
GROUP  BY sr.origin;

-- Review queue depth and age, which is a staffing signal, not a quality signal.
SELECT count(*) AS pending,
       percentile_cont(0.5) WITHIN GROUP (ORDER BY now() - decided_at) AS median_age
FROM   identity_link
WHERE  assertion IS NULL AND retired_at IS NULL;

-- Reviewer agreement with the model: how often a human overturns an auto-link.
SELECT date_trunc('week', decided_at) AS wk,
       count(*) FILTER (WHERE retired_reason = 'reviewer_overturned')::numeric
         / nullif(count(*), 0) AS overturn_rate
FROM   identity_link
WHERE  decided_by LIKE 'auto:%'
GROUP  BY 1 ORDER BY 1;

The overturn rate is the metric I watch most closely, because it is the only one that updates continuously without new labelling effort. A rising overturn rate means the model and reality have diverged, and it usually shows up weeks before anybody complains about duplicates.

Drift Signals Worth Waking Someone For

Entity resolution degrades quietly. The pipeline keeps running, the job keeps succeeding, and the output keeps getting worse. These are the monitors that have actually caught something.

Score distribution shift. Histogram the scores of all evaluated pairs weekly and compare against the trailing baseline. A shift in mass toward the review band means input quality changed — usually because someone modified an intake form. When we added a field to the self-serve reservation flow, phone completion dropped four points and the histogram showed it before anyone noticed.

Field null-rate by origin. VIN capture rate at the counter is a leading indicator of everything else. During the busiest changeover weeks it falls, and the review queue swells about ten days later. Knowing that lets you staff for it instead of being surprised.

Blocking-key explosion. The count of blocks exceeding MAX_BLOCK_SIZE, and the number of records inside them. A sudden jump almost always means a normalizer regression collapsed a field to a constant — the classic being a plate parser that starts returning empty strings and puts everyone in one bucket.

Cluster size outliers. Alert on any person cluster exceeding a threshold that is generous for a household and impossible for an individual. Fifteen is our line for retail clusters. Anything above it is either a fleet account misfiled as retail or a transitive-closure chain, and both need eyes.

Unmerge frequency by cohort. Group unmerges by the model version that created the link. If a version's unmerge rate is climbing relative to its predecessors, you have a regression with a clear owner.

Normalizer version skew. The proportion of source records whose normalizer_version lags current. If it stops falling after a deploy, your backfill is stuck, and half your comparisons are running against stale derived values.

What I Would Change On A Second Pass

Some of this design has held up for two years and some of it I regret.

I would introduce the vehicle-versus-person split on day one instead of month nine. We started with a single "customer" entity that carried a plate, and untangling that later cost more than building it properly would have. Vehicles and people have different identifiers, different stability, and different lifecycles; they were never the same problem.

I would put the review interface in front of staff earlier. The model improved far faster once the people who create the records could see the consequences of a hurried entry. Nothing sharpened VIN capture like a technician watching a merge decision hinge on a missing one.

I would resist per-value frequency weighting for longer than I did. It is theoretically correct and it made the system noticeably harder to explain to a reviewer, for a precision gain that was real but small. On a hundred thousand records, a well-chosen composite field bought more than sophisticated weighting did.

And I would treat the negative assertion as the primitive, not the afterthought. Half the operational value of this system comes from its ability to remember that two similar-looking records are definitively not the same, and we built that capability third. Positive matching is the interesting problem; recording what is known to be false is the one that stops the queue from filling with the same five pairs forever.

The counter still moves fast during changeover season, staff still type in a hurry, and people still arrive with a phone they share with a spouse and a plate they moved off a car they sold. None of that is fixable at the point of capture. What is fixable is the system's willingness to say "I am not sure," write that uncertainty down, and let a human settle it — for further reading on the identifiers themselves, the sidewall marking reference and the load index explainer cover the vehicle-side data we key off, and the service area map shows the geography that makes postal codes such weak evidence here.

Idempotent Reservations and Exclusion Constraints: Designing a Four-Bay Scheduler That Cannot Double-Book

KMJ Tire Calgary — Tue, 11 Aug 2026 16:26:29 +0000

About this article. We are a tire and oil change shop in Calgary, and the operational constraints described here are real: a small number of physical bays, jobs of tightly clustered durations, and a seasonal changeover rush that concentrates demand into a few weeks. The scheduling system itself is a design exercise written up for other developers, not a description of live production infrastructure. Every schema, query, timestamp, metric and figure below is illustrative — invented to make the reasoning concrete. Treat it as a worked design, and adapt it to your own stack.

The Duplicate That Shows Up on a Tuesday in October

Start with the domain, because it is unusually easy to reason about. A tire shop in Calgary has a handful of physical bays, jobs that run in fairly predictable blocks, and one weekend in October where half the city decides simultaneously that it is time. When a scheduler is wrong, the cost is concrete: a technician standing in a bay with nothing to do, or a customer who drove across the city for a slot that had already been consumed.

The failure worth designing against looks like this in the database:

 reservation_id                        | bay_id | service          | lower(during)             | created_at
--------------------------------------+--------+------------------+---------------------------+---------------------------
 6f2a1c9e-...-a41b                    |      3 | tire_changeover  | 2026-10-20 08:00:00-06    | 2026-10-19 21:14:02.881-06
 c0d7be34-...-9f52                    |      3 | tire_changeover  | 2026-10-20 08:00:00-06    | 2026-10-19 21:14:03.774-06

Two rows. Same bay, same start time, same customer, 893 milliseconds apart. Nobody wanted two of them. The customer was sitting in a parking lot somewhere along Deerfoot with one bar of LTE, the request took long enough that the spinner felt broken, and they tapped the submit control a second time. The mobile client had no memory of the first attempt. Our server had no reason to think the second attempt was the same intention as the first.

The result was a bay that looked occupied for two hours when it was occupied for one, and a second customer who was told there was no room. That is a revenue problem and a trust problem, and it is caused by a bug that has been solved thousands of times in other people's systems. It is worth writing down properly, because most of the write-ups I found either stop at "use an idempotency key" or drift into distributed-consensus territory that a single Postgres instance does not need.

What the Network Actually Promises You

Here is the uncomfortable primitive at the bottom of all of this. A client that issues a POST and then times out cannot distinguish between two worlds:

The request never reached the server. Nothing happened.
The request reached the server, the server did the work and committed it, and the response was lost on the way home.

There is no protocol trick that collapses those two worlds into one. TCP will not tell you. HTTP will not tell you. A load balancer that returns 504 after 30 seconds is guessing exactly as hard as the client is. This is the ordinary at-least-once delivery problem, and it has exactly one honest resolution: the server must make repetition harmless, and the client must be told precisely how to repeat.

That is what idempotency means here. Not "the operation has no side effects" — creating a reservation obviously has side effects. It means "executing this request N times produces the same observable outcome as executing it once, and returns the same answer every time."

Everything below is the machinery for that sentence.

The Work We Actually Schedule

Before the schemas, the domain, because the domain constrains the design far more than the framework does.

We do tire work and oil changes. That is the whole catalogue. It matters for the scheduler because the durations cluster tightly and the resource is coarse: a small number of physical bays, each of which can hold exactly one vehicle at a time. The service types we encode are the ones described on the public pages — seasonal changeover work, puncture repair, balancing, fresh installation, and oil service. Nothing else lands in the enum, because nothing else happens in the bays.

Illustrative durations, which is what our seed data uses in tests:

Service code	Typical bay time	Notes
`tire_changeover`	45 min	Faster when the second set is already mounted on its own rims
`tire_installation`	75 min	Mount, balance, torque, valve stems
`wheel_balancing`	40 min	Sometimes a follow-on to a road-force complaint
`tire_repair`	30 min	Dismount, inspect, patch-plug from inside, remount
`oil_change`	30 min	Only bay 1 and bay 4 are plumbed for it

Those numbers are example figures for the model, not a price list and not a promise. The point is the shape: durations vary by more than a factor of two, they are not multiples of a single grid unit, and one service type is restricted to a subset of bays. Any design that assumes uniform fixed-size slots will start lying to you within a month.

The seasonal rhythm matters too. Calgary gets a first real snowfall warning somewhere in October, and the request volume on the changeover pages goes up by an order of magnitude in about six hours. That is the week the concurrency bugs surface, because that is the week two people genuinely are competing for the same 8:00 AM slot in the same bay, and the week a cell tower on the Trail is congested enough to produce ambiguous timeouts.

Two Different Problems Wearing One Costume

The failure I opened with is really two failures that happen to look identical from the customer's side.

Problem one is request duplication. The same intention arrives twice. This is a transport-layer artifact. The fix lives at the edge of your API and is about recognising that two byte streams represent one decision.

Problem two is resource contention. Two genuinely different intentions arrive and both want the last available bay. This is a data-integrity problem. The fix lives in the storage engine and is about making an invalid state unrepresentable.

Neither mechanism solves the other. An idempotency key will not stop two different customers from overbooking bay 3. An exclusion constraint will not stop one customer from creating two reservations in two different bays because their phone retried. If you build only one, you will spend a quarter chasing the symptoms of the other. Build both, and know which one you are relying on for which failure.

The Idempotency Record, In Full

Start with the table, because the columns encode most of the decisions.

CREATE TABLE idempotency_records (
  requester_id     uuid        NOT NULL,
  endpoint         text        NOT NULL,
  idem_key         text        NOT NULL,
  request_digest   bytea       NOT NULL,
  state            text        NOT NULL
                   CHECK (state IN ('in_flight', 'completed', 'failed')),
  response_status  smallint,
  response_body    jsonb,
  result_ref       uuid,
  lease_until      timestamptz,
  finished_at      timestamptz,
  expires_at       timestamptz NOT NULL,
  first_seen_at    timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (requester_id, endpoint, idem_key)
);

CREATE INDEX idempotency_records_expiry
  ON idempotency_records (expires_at)
  WHERE state <> 'in_flight';

Three things about that primary key.

It is scoped by requester_id. Keys are client-generated, and clients are not coordinated with each other. If two different mobile installs both use a UUIDv4 you are statistically fine, but if some integration partner uses an incrementing counter you will get collisions between tenants and start replaying one customer's response to another. Scoping by requester makes that impossible rather than unlikely.

It is scoped by endpoint. The same key reused against a different route is almost certainly a client bug, and treating the two as unrelated records is far kinder than replaying a reservation payload to a cancellation route.

request_digest is a hash, not the body. Storing the full body is tempting for debugging and terrible for retention. A SHA-256 over a canonical serialisation is 32 bytes, tells you everything you need for the equality check, and carries no plate numbers or phone numbers into a table you will eventually forget to encrypt.

Fingerprinting a Request Without Lying to Yourself

The digest is where most implementations quietly break. If you hash the raw bytes, a client that reorders JSON keys between attempts — which many HTTP libraries will happily do — produces a different digest for an identical intention, and your server rejects a legitimate retry.

So canonicalise first, and be explicit about what is excluded.

import hashlib
import json

VOLATILE_FIELDS = frozenset({
    "client_timestamp",   # regenerated on every attempt
    "device_id",          # not part of the intention
    "trace_id",           # observability plumbing
    "attempt",            # the client's own retry counter
})

def request_digest(payload: dict) -> bytes:
    stable = {k: v for k, v in payload.items() if k not in VOLATILE_FIELDS}
    canonical = json.dumps(stable, sort_keys=True, separators=(",", ":"),
                           ensure_ascii=False)
    return hashlib.sha256(canonical.encode("utf-8")).digest()

Two rules I would enforce in review. First, the exclusion list is an allowlist inverted, and it must be small and deliberate; every field you drop is a field where a genuine change slips past the equality check. Second, nested structures need the same treatment recursively if your serialiser does not sort deeply — json.dumps(sort_keys=True) does, but a Protobuf-to-dict conversion might not.

Same Key, Different Body

Now the interesting case. A request arrives with a key we have already seen, but the digest does not match what we stored.

Return 409 Conflict. Do not process it. Do not overwrite the stored record. Do not silently replay the old response either.

The reasoning is that you are being asked to do something incoherent, and every alternative is worse:

Process it as new. You have just created a second reservation under a key that was supposed to guarantee at most one. The key is now decorative.
Replay the old response. The client asked for a 9:30 slot and you hand back a receipt for 8:00. It will believe you. Somebody drives to the wrong time.
Update the record and process it. Same as processing it as new, with extra steps and a corrupted audit trail.

409 is the only answer that preserves the contract, and the body should say why in machine-readable form:

{
  "error": "idempotency_key_reuse",
  "message": "This key was already used for a request with a different body.",
  "key": "01J9XW7Q4S6R8T2V3M5N7P9Q1R",
  "first_seen_at": "2026-10-19T21:14:02.881-06:00"
}

That error code matters because it separates two 409s that mean entirely different things. idempotency_key_reuse is a client defect and must never be retried. slot_unavailable, which we will get to, is a legitimate business outcome and should be surfaced to a human, not to a retry loop. If both return a bare 409 with prose, some well-meaning SDK will retry the first one forever.

The Lifecycle of a Record

A record is a tiny state machine with three terminal-ish states:

                 claim (INSERT ... ON CONFLICT DO NOTHING)
                          |
                          v
                    +-----------+
                    | in_flight |
                    +-----+-----+
                          |
          success         |          deterministic failure
      +-------------------+-------------------+
      |                                       |
      v                                       v
+-----------+                           +----------+
| completed |                           |  failed  |
+-----------+                           +----------+
      |                                       |
      +---------------+-----------------------+
                      |
                  expires_at passes, row is reaped

Transient failures — a lost connection to the database, a 500 from a downstream service, a deadlock — do not move the record to failed. They delete the claim entirely, or let its lease lapse, so the client's retry gets a clean attempt. Only deterministic outcomes are recorded, because only deterministic outcomes will be identical on replay. If you persist a 503 and replay it for the next 24 hours, you have built a machine for turning a five-second blip into a day-long outage for one customer.

There is a fourth implicit state worth naming: abandoned. A process claims a key, writes in_flight, and then the container is evicted mid-transaction. The row is stranded. That is what lease_until is for. Any record whose lease has expired is fair game for reclamation, and reclamation is just a conditional update:

UPDATE idempotency_records
   SET state       = 'in_flight',
       lease_until = now() + interval '30 seconds',
       request_digest = $4
 WHERE requester_id = $1
   AND endpoint     = $2
   AND idem_key     = $3
   AND state        = 'in_flight'
   AND lease_until  < now()
RETURNING *;

Pick the lease to be comfortably longer than your slowest legitimate handler and comfortably shorter than your client's first retry delay. Ours is 30 seconds against a handler p99 of about 400 milliseconds and a first client retry at 2 seconds, which is generous in both directions on purpose.

Insert First, Ask Questions Later

The naive claim is SELECT then INSERT if absent. That is the same race we are trying to eliminate, one layer up. Two concurrent duplicates both see nothing, both insert, one gets a primary-key violation, and now your handler has an error path it did not plan for.

Do the claim as a single statement and let the index arbitrate:

INSERT INTO idempotency_records
       (requester_id, endpoint, idem_key, request_digest,
        state, lease_until, expires_at)
VALUES ($1, $2, $3, $4,
        'in_flight', now() + interval '30 seconds', now() + interval '30 days')
    ON CONFLICT (requester_id, endpoint, idem_key) DO NOTHING
RETURNING first_seen_at;

If you get a row back, you own the claim and you proceed. If you get zero rows, somebody else owns it or owned it, and you go read the existing record to decide what to say. That branch is where the three answers live: replay the stored response, return 409 for a digest mismatch, or tell the caller that an attempt is currently running.

For the third case, I favour failing fast over waiting:

409 Conflict
Retry-After: 1
{"error": "request_in_progress", "key": "01J9XW..."}

Holding the HTTP connection open while polling for the other transaction to finish is superficially friendlier and operationally awful. It ties up a worker, it converts a duplicate-request problem into a connection-pool-exhaustion problem, and during the October surge it is precisely the moment you cannot afford either. A client that receives request_in_progress and honours Retry-After gets the real answer one second later, having cost you nothing.

Capacity Is a Physical Fact, Not a Counter

Now the second half of the problem, and the half people get wrong more often.

We have four indoor bays. Not "a capacity of four" — four actual concrete rectangles, two of which have the oil-service plumbing, one of which is closest to the balancer and therefore preferred for road-force work. That distinction is not pedantry. If you model capacity as an integer you decrement, you have thrown away the constraint that a specific vehicle occupies a specific bay for a specific interval, and you will not be able to answer "which bay is this vehicle going into" without inventing an assignment step later, under time pressure, in the middle of the rush.

CREATE TYPE service_kind AS ENUM (
  'tire_changeover',
  'tire_installation',
  'wheel_balancing',
  'tire_repair',
  'oil_change'
);

CREATE TABLE bays (
  bay_id       smallint    PRIMARY KEY,
  label        text        NOT NULL,
  oil_plumbed  boolean     NOT NULL DEFAULT false,
  active       boolean     NOT NULL DEFAULT true
);

CREATE TABLE reservations (
  reservation_id  uuid         PRIMARY KEY DEFAULT gen_random_uuid(),
  bay_id          smallint     NOT NULL REFERENCES bays (bay_id),
  service         service_kind NOT NULL,
  during          tstzrange    NOT NULL,
  status          text         NOT NULL DEFAULT 'held'
                  CHECK (status IN ('held','confirmed','cancelled','completed')),
  customer_ref    uuid         NOT NULL,
  plate           text,
  raised_at       timestamptz  NOT NULL DEFAULT now(),
  CONSTRAINT during_is_bounded CHECK (
    lower(during) IS NOT NULL AND upper(during) IS NOT NULL
  )
);

Note during tstzrange rather than a start column and an end column. That choice is what makes the rest of this section short.

Why SELECT-Then-INSERT Cannot Work

The obvious handler reads:

-- Step 1
SELECT count(*) FROM reservations
 WHERE bay_id = 3
   AND status IN ('held','confirmed')
   AND during && tstzrange('2026-10-20 08:00-06', '2026-10-20 08:45-06', '[)');

-- Step 2, if the count was zero
INSERT INTO reservations (bay_id, service, during, customer_ref)
VALUES (3, 'tire_changeover',
        tstzrange('2026-10-20 08:00-06', '2026-10-20 08:45-06', '[)'),
        '...');

Under Postgres's default READ COMMITTED isolation, each statement sees a snapshot taken at the start of that statement. Uncommitted rows from other transactions are invisible. So two transactions running this pair concurrently both observe an empty bay, both insert, and both commit. No error is raised. Nothing in the database objects. You have a read-modify-write race with a comfortable window measured in milliseconds, which during a surge is more than wide enough to hit several times an hour.

This is not a Postgres quirk. It is what READ COMMITTED is defined to do. The check you performed was a predicate over rows that did not exist yet, and no isolation level below SERIALIZABLE gives predicates any protection.

Two Transactions, One Bay: The Exact Interleaving

Here is the sequence, written out, because I find the abstract version never lands the way a trace does. T1 and T2 are two application workers handling what turned out to be the same customer's duplicate submission, though it would look identical for two different customers.

Time	T1	T2	Committed state
0 ms	`BEGIN;`		bay 3 at 08:00 is free
4 ms	`SELECT count(*) ... during && [08:00,08:45)` returns 0		unchanged
9 ms		`BEGIN;`	unchanged
12 ms		`SELECT count(*) ...` returns 0	unchanged
18 ms	`INSERT ... reservation A` succeeds		A exists but is invisible to T2
21 ms		`INSERT ... reservation B` succeeds	B exists, invisible to T1
25 ms	`COMMIT;`		A is durable
27 ms		`COMMIT;`	A and B are both durable

At 27 ms the invariant is broken and no software component noticed. The only reason we ever found out is that a service advisor looked at a printed run sheet and saw the same plate twice.

Now the same trace with the exclusion constraint in place, which we will define in a moment:

Time	T1	T2	What the engine does
18 ms	`INSERT ... A` succeeds		GiST index entry taken for `(3, [08:00,08:45))`
21 ms		`INSERT ... B`	blocks — conflicting index entry is uncommitted
25 ms	`COMMIT;`	(still blocked)	A becomes durable, lock released
25.1 ms		raises `23P01 exclusion_violation`	B never exists

T2's handler catches 23P01, maps it to slot_unavailable, and returns a 409 with a list of nearby alternatives. The invariant held without the application having to think about it.

Making Overbooking Physically Impossible

CREATE EXTENSION IF NOT EXISTS btree_gist;

ALTER TABLE reservations
  ADD CONSTRAINT reservations_one_vehicle_per_bay
  EXCLUDE USING gist (
    bay_id  WITH =,
    during  WITH &&
  ) WHERE (status IN ('held', 'confirmed'));

Read that as: no two rows in the qualifying set may have both an equal bay_id and overlapping during ranges. btree_gist is what lets a scalar column like bay_id participate in a GiST index alongside a range column; without it, the equality operator has no GiST operator class.

Three properties make this the right primitive rather than one option among several.

It is enforced by the storage engine, so it holds regardless of which code path performs the insert. The admin console, the batch importer that loads fleet work, a psql session at 11 PM, a future service written by somebody who never read this article — all of them are covered. Application-level checks protect only the applications that remember to perform them.

It works at READ COMMITTED. You do not need SERIALIZABLE, you do not need a retry loop for serialization failures, and you do not pay the SSI bookkeeping cost on every read.

The partial WHERE clause means cancelled and completed rows drop out of the constraint automatically. A cancelled 08:00 slot stops blocking new work the instant its status changes, with no tombstone handling and no separate cleanup.

The cost is real but small: the GiST index is larger and slower to update than a btree, and range queries against it are not always as fast as a well-chosen composite btree on (bay_id, start_time). At our volume that is irrelevant. At a scale where it matters, you keep the exclusion constraint for correctness and add a btree for the read path.

Ranges Beat Timestamp Pairs When Durations Vary

The half-open bound notation '[)' in tstzrange(start, finish, '[)') is not decoration. It says the range includes its lower bound and excludes its upper. That is what makes a job ending at 09:00 and a job starting at 09:00 not overlap, which is exactly the semantics you want for back-to-back work.

Get this wrong and you produce one of two bugs. With inclusive upper bounds '[]', consecutive jobs conflict and your bay utilisation drops by a slot per boundary. With exclusive lower bounds '()', zero-length and adjacent ranges behave in ways that will surprise you at 7 AM.

The overlapping-duration case from the assignment brief is where ranges really earn their keep. Consider a 75-minute installation starting at 09:00 in bay 2, and someone trying to place a 30-minute repair at 09:45 in the same bay:

SELECT tstzrange('2026-10-20 09:00-06','2026-10-20 10:15-06','[)')
    && tstzrange('2026-10-20 09:45-06','2026-10-20 10:15-06','[)') AS conflicts;
-- conflicts => true

With a start column and a duration column you would be writing that predicate by hand in every query, and every hand-written version is a chance to invert a comparison. With ranges the && operator is the predicate, it is the same predicate the index uses, and there is no second implementation to drift.

A related benefit: buffer time becomes a range operation instead of arithmetic scattered through the code. If you want ten minutes of cushion between vehicles for the pull-in and pull-out, widen the stored range at write time and let the constraint do the rest.

-- Buffered range helper, applied at insert time
SELECT tstzrange(
         lower(r.during) - interval '5 minutes',
         upper(r.during) + interval '5 minutes',
         '[)')
  FROM (SELECT tstzrange($1, $2, '[)') AS during) r;

The Unique Partial Index Alternative

If your durations really are uniform, a unique partial index is simpler and cheaper:

CREATE UNIQUE INDEX one_job_per_bay_slot
    ON reservations (bay_id, lower(during))
 WHERE status IN ('held', 'confirmed');

This gives you the same physical impossibility with a plain btree, no extension, and no GiST overhead. It is a perfectly good answer for a fixed grid — every job is exactly 30 minutes, every start is on the half hour, nothing ever runs long.

It collapses the moment durations vary. A 75-minute installation starting at 09:00 has a distinct lower(during) from a 30-minute repair starting at 09:45, so both indexes entries are unique, and both rows are accepted despite occupying the same bay at the same time. This is a classic way for a "quick" change allowing long jobs to reintroduce the exact bug the index was meant to kill. If there is any chance your service catalogue will grow — and a catalogue covering oil service alongside tire work already mixes durations — start with the range type.

Advisory Locks and Row Locks: Where They Fit

Two other tools come up constantly in this conversation, and both have a place.

SELECT ... FOR UPDATE on a parent row serialises writers through a row lock:

BEGIN;
SELECT bay_id FROM bays WHERE bay_id = 3 FOR UPDATE;
-- every writer for bay 3 now queues here
SELECT count(*) FROM reservations WHERE bay_id = 3 AND during && $1
                                    AND status IN ('held','confirmed');
INSERT INTO reservations (...) VALUES (...);
COMMIT;

This is correct, and it is easy to reason about. The weakness is that its correctness is a convention. Nothing forces the next writer to take the lock. The importer written six months later will not, and the constraint you thought you had was really an agreement between the two functions that happened to exist when you wrote it.

Advisory locks are the same idea without a row to hang it on, useful when the thing you are serialising is not a table row:

SELECT pg_advisory_xact_lock(
  hashtextextended(format('bay:%s:%s', $1::text, $2::date::text), 0)
);

pg_advisory_xact_lock releases automatically at transaction end, which is almost always what you want; the session-scoped variant leaks locks when a pooled connection is handed back without cleanup. Note the hash collision surface: two distinct keys can map to the same bigint, and the consequence is spurious serialisation rather than a correctness bug, so it is tolerable — but it is another reason to prefer a constraint that names the real objects.

My rule: use the exclusion constraint as the source of truth, and reach for a lock only when you need to serialise a multi-row decision that no single constraint can express. Assigning a vehicle to the best available bay out of four, for example, involves reading all four and picking one; a lock makes that read-then-choose deterministic, while the constraint still catches you if the logic is wrong.

Isolation Levels, Stated Plainly

Worth being precise, because this is where hand-waving does the most damage.

READ COMMITTED (the Postgres default): each statement sees rows committed before that statement began. It prevents dirty reads. It does not prevent non-repeatable reads, phantom reads, or the write skew that our double-insert is a form of. Two transactions can each observe "no conflict" and each create one. This is the level at which the exclusion constraint saves you, because the constraint is enforced in the index, not in a snapshot.

REPEATABLE READ: one snapshot for the whole transaction. Postgres's implementation gives you snapshot isolation, which does prevent non-repeatable and phantom reads within your own transaction. It still does not prevent write skew across transactions, because two transactions reading disjoint snapshots and writing disjoint rows never collide. Our race survives here untouched. People are frequently surprised by this.

SERIALIZABLE: Postgres uses Serializable Snapshot Isolation, tracking read-write dependencies between concurrent transactions and aborting one when it detects a dangerous structure. This does catch our race. T2 fails at commit with SQLSTATE 40001, serialization_failure, and you retry the whole transaction from the top.

SERIALIZABLE is genuinely correct and I do not want to talk anyone out of it. But be aware of the bill. Every transaction in the system pays predicate-lock bookkeeping, not only the ones you were worried about. Aborts are probabilistic and can fire on transactions with no real conflict, so every write path needs a retry loop with backoff, including the ones you wrote before you turned it on. And the failure mode under load is a retry storm precisely when load is highest.

The comparison in one table:

Mechanism	Stops our race?	Isolation needed	Enforced against all writers	Retry loop required
App-level check, no lock	No	any	No	No
`FOR UPDATE` on bay row	Yes	READ COMMITTED	No, by convention only	No
Advisory transaction lock	Yes	READ COMMITTED	No, by convention only	No
Unique partial index	Yes, fixed grid only	READ COMMITTED	Yes	No
GiST exclusion constraint	Yes, any durations	READ COMMITTED	Yes	No
SERIALIZABLE, no constraint	Yes	SERIALIZABLE	Yes	Yes, everywhere

We landed on the exclusion constraint at READ COMMITTED, with a transaction-scoped advisory lock only in the auto-assignment path.

The Handler, Start to Finish

Putting both halves together. This is psycopg3-flavoured Python, trimmed of logging and validation but structurally what runs.

import uuid
from psycopg import errors

LEASE = "30 seconds"
RECORD_TTL = "30 days"

class KeyReuse(Exception): ...
class AttemptRunning(Exception): ...
class SlotUnavailable(Exception): ...

CLAIM = """
INSERT INTO idempotency_records
       (requester_id, endpoint, idem_key, request_digest,
        state, lease_until, expires_at)
VALUES (%(req)s, %(ep)s, %(key)s, %(dig)s, 'in_flight',
        now() + interval %(lease)s, now() + interval %(ttl)s)
    ON CONFLICT (requester_id, endpoint, idem_key) DO NOTHING
RETURNING first_seen_at
"""

FETCH = """
SELECT state, request_digest, response_status, response_body, lease_until
  FROM idempotency_records
 WHERE requester_id = %(req)s AND endpoint = %(ep)s AND idem_key = %(key)s
"""

PLACE = """
INSERT INTO reservations (bay_id, service, during, customer_ref, plate)
VALUES (%(bay)s, %(svc)s, tstzrange(%(from)s, %(to)s, '[)'),
        %(cust)s, %(plate)s)
RETURNING reservation_id
"""

SETTLE = """
UPDATE idempotency_records
   SET state = 'completed', response_status = %(status)s,
       response_body = %(body)s, result_ref = %(ref)s,
       finished_at = now(), lease_until = NULL
 WHERE requester_id = %(req)s AND endpoint = %(ep)s AND idem_key = %(key)s
"""

def place_reservation(conn, requester, key, payload):
    dig = request_digest(payload)
    args = {"req": requester, "ep": "POST /v1/reservations", "key": key}

    with conn.transaction():
        claimed = conn.execute(
            CLAIM, {**args, "dig": dig, "lease": LEASE, "ttl": RECORD_TTL}
        ).fetchone()

        if claimed is None:
            row = conn.execute(FETCH, args).fetchone()
            state, stored_dig, status, body, lease_until = row
            if stored_dig != dig:
                raise KeyReuse(key)
            if state == "in_flight" and lease_until > utcnow():
                raise AttemptRunning(key)
            if state in ("completed", "failed"):
                return status, body          # verbatim replay
            # lease has lapsed: fall through and reclaim it
            conn.execute(RECLAIM, {**args, "dig": dig, "lease": LEASE})

        try:
            ref = conn.execute(PLACE, {
                "bay": payload["bay_id"], "svc": payload["service"],
                "from": payload["starts_at"], "to": payload["ends_at"],
                "cust": payload["customer_ref"], "plate": payload.get("plate"),
            }).fetchone()[0]
        except errors.ExclusionViolation:
            body = {"error": "slot_unavailable", "bay_id": payload["bay_id"]}
            conn.execute(SETTLE, {**args, "status": 409,
                                  "body": Jsonb(body), "ref": None})
            raise SlotUnavailable(payload["bay_id"])

        result = {"reservation_id": str(ref), "status": "held"}
        conn.execute(SETTLE, {**args, "status": 201,
                              "body": Jsonb(result), "ref": ref})
        return 201, result

The important structural property: the claim, the reservation insert, and the settle all live inside one transaction. If any of them fails for a transient reason, the whole thing rolls back including the claim, and the client's retry finds no record and gets a genuinely fresh attempt. That is what makes transient failures safe to retry without leaving zombie in_flight rows behind.

Notice also that slot_unavailable is settled into the record as a completed 409 before the exception propagates. That is deliberate. A capacity rejection is a deterministic outcome for that exact request body, and replaying it is correct: if you ask for the same bay at the same time tomorrow morning with the same key, the answer has not changed.

What the Client Owes the Server

Idempotency is a two-party contract, and half of it is client-side discipline. The rule that gets violated most often is the simplest one.

Reuse the same key on retry. A retry is not a new intention. If your HTTP wrapper mints a fresh UUID on every attempt, every one of your carefully designed server mechanisms is bypassed, and you have built a very sophisticated way to create duplicates. Generate the key when the human commits to the action — the moment the submit control is pressed — and hold it for the lifetime of that intention, including across app restarts if you have an offline queue.

Which responses are safe to retry:

Status / condition	Retry?	Why
Connection reset, DNS failure, TLS handshake failure	Yes	Request may never have landed
Client-side timeout, no response	Yes	Ambiguous by construction; this is the core case
408, 425	Yes	Server explicitly says the attempt did not complete
429	Yes, after `Retry-After`	Rate limit, not a semantic error
500, 502, 503, 504	Yes, with backoff	Transient or ambiguous
409 `request_in_progress`	Yes, after `Retry-After`	Another attempt of yours is mid-flight
409 `slot_unavailable`	No	Deterministic; retrying returns the same answer forever
409 `idempotency_key_reuse`	No	Client defect; escalate, do not loop
400, 422	No	The payload is wrong and will stay wrong
401, 403	No	Credentials, not concurrency
404	No	Nothing to do

Two of those rows are the ones I would put in a code review checklist: retrying slot_unavailable is how you build a client that hammers a full facility until the customer force-quits the app, and retrying idempotency_key_reuse is how you turn one bug into a sustained one.

Backoff, Jitter, and the Herd After a Snowfall Warning

Fixed-interval retries synchronise. If a thousand clients all get a 503 at the same instant because a deploy briefly dropped a replica, and all of them retry at exactly 1s, 2s, and 4s, you have built a distributed drum circle that will keep the service down long after the original cause is gone. Calgary gives us a very reliable trigger for this: the hour after a snowfall warning is published, when everyone in the city thinks about winter rubber at once.

Full jitter is the version I would default to:

import random
import time

BASE = 0.25      # seconds
CAP  = 20.0      # seconds
MAX_ATTEMPTS = 6

def with_retries(send, idem_key):
    for attempt in range(MAX_ATTEMPTS):
        outcome = send(idem_key)          # SAME key every time
        if outcome.terminal:
            return outcome
        ceiling = min(CAP, BASE * (2 ** attempt))
        time.sleep(random.uniform(0, ceiling))
    raise RetriesExhausted(idem_key)

random.uniform(0, ceiling) rather than ceiling alone is the whole trick: it spreads the herd across the interval instead of stacking it on the boundary. Equal jitter (ceiling/2 + random.uniform(0, ceiling/2)) is a reasonable variant when you care about a floor on latency. Decorrelated jitter is better still under sustained pressure, but full jitter is easy to explain to whoever is on rotation at 6 AM, and that has value.

Two additions that matter more than the exact formula. Cap total elapsed time, not just attempt count, because six attempts with a 20-second cap can span two minutes and the human gave up ninety seconds ago. And carry an attempt counter in a header for observability, excluded from the digest, so you can graph how deep clients are actually going.

Choosing a TTL You Can Defend

expires_at is the field where a lazy default becomes a correctness bug six months later.

The rule is: the TTL must exceed the longest interval over which a client might legitimately replay the same key. If a record expires and is deleted, and then the original request arrives one more time, your server has no memory of it and will happily create a second reservation. The idempotency guarantee has a shelf life, and you chose it.

Twenty-four hours is the common default and it is often too short. Ours is 30 days, for reasons that are specific and boring:

The mobile client has an offline queue. A phone that loses signal in a parkade, gets put on a charger, and is not opened until Monday will drain that queue on Monday. A weekend plus a holiday is easily 72 hours.
Integration partners who submit commercial and fleet work run batch jobs whose failure handling is, charitably, unhurried. A stuck batch resubmitted the following week is a real thing that has happened.
The rows are small. Thirty days of records at our volume is a few hundred megabytes. Buying a month of safety for that is not a difficult trade.

If you cannot make the TTL long enough — and some systems genuinely cannot — then add a second line of defence that does not expire. A natural-key uniqueness constraint on the business meaning of the request survives idempotency-record expiry:

CREATE UNIQUE INDEX reservations_no_repeat_intent
    ON reservations (customer_ref, service, lower(during))
 WHERE status IN ('held', 'confirmed');

That will not catch every duplicate — a customer legitimately placing two jobs for two vehicles at the same time trips it, so you may need the vehicle in the key — but it converts a silent duplicate into a loud constraint violation, and loud is always better.

Reaping Old Records Without Hurting Live Traffic

A single unbounded DELETE FROM idempotency_records WHERE expires_at < now() will, on a busy table, take locks for long enough to matter and generate a spike of WAL and autovacuum work at the worst possible moment. Batch it:

WITH doomed AS (
  SELECT ctid
    FROM idempotency_records
   WHERE expires_at < now()
     AND state <> 'in_flight'
   ORDER BY expires_at
   LIMIT 5000
)
DELETE FROM idempotency_records t
 USING doomed d
 WHERE t.ctid = d.ctid;

Loop that until it deletes fewer than the limit, sleep between iterations, and run it well outside the morning rush. The state <> 'in_flight' guard is not optional: deleting a claim out from under a running handler produces exactly the duplicate you built the table to prevent.

The better answer at volume is to stop deleting rows at all. Partition by day and drop whole partitions:

CREATE TABLE idempotency_records (
  ...
) PARTITION BY RANGE (first_seen_at);

CREATE TABLE idempotency_records_p2026_10_20
  PARTITION OF idempotency_records
  FOR VALUES FROM ('2026-10-20') TO ('2026-10-21');

-- retirement, once the window has passed
DROP TABLE idempotency_records_p2026_09_20;

There is a real tradeoff hiding in that snippet and I want to name it rather than skip past it. Postgres requires the partition key to be part of any unique constraint on a partitioned table, so the primary key becomes (first_seen_at, requester_id, endpoint, idem_key). Uniqueness is now enforced within a partition, not across the table. If the same key arrives on two different days, the index will not stop you. In practice that is fine when your retention window vastly exceeds any plausible replay window, and it is a live hazard when it does not. Decide on purpose.

Reconciliation: Finding What Slipped Through

Constraints prevent the failures you anticipated. Reconciliation finds the ones you did not. Two queries run nightly against the previous day.

Near-simultaneous identical intentions, which is the fingerprint of a client that is not reusing its key properly:

WITH ordered AS (
  SELECT reservation_id, customer_ref, service, during, raised_at,
         LAG(reservation_id) OVER w AS prior_id,
         LAG(raised_at)      OVER w AS prior_raised
    FROM reservations
   WHERE status IN ('held','confirmed')
     AND raised_at >= now() - interval '1 day'
  WINDOW w AS (PARTITION BY customer_ref, service, lower(during)
               ORDER BY raised_at)
)
SELECT customer_ref, reservation_id, prior_id,
       raised_at - prior_raised AS gap
  FROM ordered
 WHERE prior_id IS NOT NULL
   AND raised_at - prior_raised < interval '10 minutes'
 ORDER BY gap;

And one customer holding overlapping slots in different bays, which the per-bay constraint cannot see:

SELECT a.customer_ref,
       a.reservation_id AS earlier,
       b.reservation_id AS later,
       a.during * b.during AS shared_window
  FROM reservations a
  JOIN reservations b
    ON a.customer_ref = b.customer_ref
   AND a.reservation_id < b.reservation_id
   AND a.during && b.during
 WHERE a.status IN ('held','confirmed')
   AND b.status IN ('held','confirmed');

The * operator there is range intersection, which gives you the exact overlapping window rather than a boolean. Handy in a report a human has to act on.

A third check worth running compares the count of completed idempotency records against the count of reservations created in the same window. A persistent gap means some write path is bypassing the claim entirely, and that path is your next incident.

Metrics That Earn Their Storage

Instrument the branches, not the endpoint. The interesting signal is in which arm of the state machine traffic takes.

idempotency_claims_total — new claims. Your baseline for everything else.
idempotency_replays_total{outcome="completed"|"failed"} — verbatim replays served. A rising ratio against claims means clients are retrying more, which usually means latency has crept up somewhere upstream. That makes it a leading indicator rather than a lagging one, which is why it belongs on a dashboard instead of in a weekly report.
idempotency_digest_mismatch_total — 409s for key reuse. This should be flat at approximately zero. Any movement is a client release regression; alert on it.
idempotency_in_flight_rejections_total — how often a duplicate arrives while the original is still running. Correlates directly with handler latency.
idempotency_lease_reclaims_total — abandoned claims recovered. Non-zero means processes are dying mid-request.
reservation_exclusion_violations_total{bay_id} — genuine capacity contention. Per-bay labels tell you which bay is the bottleneck, which is an operational answer, not just an engineering one.
idempotency_record_age_seconds — histogram of now() - first_seen_at at replay time. This is how you validate your TTL empirically instead of by argument. If the p99 is creeping toward your expiry window, lengthen it.
reap_rows_deleted_total and reaper duration. A reaper that stops keeping up is a slow-motion disk alert.

The two I would put on a wall: digest mismatches, because they are always a bug, and the replay-to-claim ratio, because it is the earliest signal that something is degrading for real users.

A Concurrency Test That Actually Fails on the Naive Version

A test that passes against both implementations is worse than no test, because it tells you the race is handled when it is not. The requirement is that the test reliably fails when you remove the constraint.

Three ingredients: a real Postgres (not SQLite, whose locking model will hide the bug), enough concurrency to make the window wide, and a barrier so every worker arrives at the critical section together.

import threading
import concurrent.futures as cf
import pytest

WORKERS = 32

def test_only_one_reservation_survives_the_stampede(pool, seeded_bay):
    gate = threading.Barrier(WORKERS)
    window = ("2026-10-20T08:00:00-06:00", "2026-10-20T08:45:00-06:00")

    def attempt(n: int):
        body = {
            "bay_id": seeded_bay, "service": "tire_changeover",
            "starts_at": window[0], "ends_at": window[1],
            "customer_ref": str(uuid.uuid4()),
        }
        gate.wait(timeout=10)                 # release all threads together
        with pool.connection() as conn:
            try:
                return place_reservation(conn, REQUESTER, f"k-{n}", body)
            except SlotUnavailable:
                return None

    with cf.ThreadPoolExecutor(max_workers=WORKERS) as ex:
        results = list(ex.map(attempt, range(WORKERS)))

    assert sum(r is not None for r in results) == 1

    with pool.connection() as conn:
        rows = conn.execute(
            "SELECT count(*) FROM reservations "
            "WHERE bay_id = %s AND status IN ('held','confirmed')",
            (seeded_bay,)).fetchone()[0]
    assert rows == 1, f"overbooked: {rows} rows survived"

Note that each worker uses a different idempotency key and a different customer. That is deliberate: this test targets the capacity mechanism specifically, with the duplicate-suppression mechanism removed from the picture. Its twin uses one shared key across all 32 workers and asserts that exactly one row is created and that every other worker got either a replay of the same reservation_id or AttemptRunning.

If the stampede test is flaky against the naive implementation — sometimes it produces 2 rows, sometimes 1 — widen the window deterministically. Inject a controllable pause between the read and the write in a test build:

if HOOK := os.environ.get("RACE_HOOK_MS"):
    time.sleep(int(HOOK) / 1000.0)

With RACE_HOOK_MS=50, the naive path fails every single run, and the exclusion-constraint path still produces exactly one row. That is the pair of outcomes that proves the mechanism rather than the timing.

One more test I recommend and rarely see: assert the error code, not just that an exception occurred. A test that accepts any exception will keep passing when a typo turns your capacity rejection into a NameError.

Where This Design Still Bites

I would rather list the sharp edges than pretend there are none.

Retries at the load balancer are invisible to you. If your ingress retries idempotent-looking requests on its own — and some do, by default, for reads — you can get a duplicate that never passed through client code and therefore has no key discipline behind it. Check your ingress configuration.

Clock skew shifts the meaning of lease_until and expires_at if you compute them in application code across several hosts. Compute them in SQL with now() so a single authority owns time. Every timestamp in the DDL above does this.

Cancellation and rescheduling need their own keys, and the same 409 discipline. A cancel that runs twice is usually harmless; a reschedule that runs twice is a duplicate wearing a different hat.

Multi-resource jobs break the single-constraint model. A vehicle needing both a bay and the balancer for part of its stay is two resources with two overlap constraints, and the ordering of those two inserts becomes a deadlock question. The pragmatic option is widening the bay range to cover the whole job, which is slightly wasteful and completely safe. The general version is a lock ordering convention, and it is the part of this design I like least.

Off-site work would be a separate resource pool entirely. A mobile service unit is not a bay, its capacity is bounded by drive time rather than floor space, and the constraint governing it also has to encode the geographic coverage rules. Same idempotency machinery, different exclusion predicate — and a travel-time term that the bay model does not need at all.

What This Design Buys You

The point is not that duplicates get cleaned up faster. It is that the class of bug stops being reachable. Once non-overlap is a schema constraint rather than a convention, a new service path — say after-hours handling — inherits the guarantee without anyone writing fresh concurrency code for it. That is the entire argument for pushing the invariant down into the database instead of leaving it in a function somebody has to remember to invoke.

The design in one paragraph, for anyone skimming to the end: generate the key on the client at the moment of human intent and reuse it on every retry; claim it server-side with a single conditional insert; store a canonical digest and the serialised response; return 409 for a mismatched body and 409 with Retry-After for a concurrent attempt; model bays as rows and occupancy as a tstzrange; enforce non-overlap with a GiST exclusion constraint so no write path can violate it regardless of isolation level; pick a TTL longer than your worst realistic replay delay and back it with a natural-key index if you cannot; reap in batches or by dropping partitions; reconcile nightly; and write the stampede test with a barrier so it fails loudly against the naive implementation.

The work this machinery would schedule is described in plain language on the customer-facing scheduling pages, and the reasoning behind the service definitions themselves lives in our tire education material. Software of this kind exists to make sure the physical thing — a vehicle, a bay, a technician, forty-five minutes in October — matches what the database says. Everything above exists to keep those two pictures identical.

Encoding Tire Repairability as a Versioned Decision Table Instead of Nested Conditionals

KMJ Tire Calgary — Mon, 10 Aug 2026 16:17:53 +0000

Encoding Tire Repairability as a Versioned Decision Table Instead of Nested Conditionals

KMJ Tire is a Calgary operation whose entire service catalogue is tires and oil changes. Sitting beside a business shaped like that, the obvious piece of software to want is a work-order pre-screen: feed it a damage assessment, get back a signal about whether a damaged tire is likely to go back on the vehicle or likely to be scrapped. The first version of such a thing is always a function with a lot of if statements in it. Four hundred lines later it has an ordering bug nobody can see, and it produces answers nobody can explain afterwards.

What follows is a design study of the replacement: an ordered, data-driven rule set — a decision table with explicit precedence, three-valued outcomes, per-rule provenance, and version pinning so a verdict issued eleven months ago can be reproduced under the criteria that were in force at the time. The domain grounding is real; the system is a design exercise rather than a description of live production infrastructure, and every figure in it is illustrative. The domain is tires, but the shape of the problem is not: safety-adjacent classification with incomplete inputs, where the wrong answer is worse than no answer.

One boundary up front, because it matters more than any code in this article. The criteria below are the industry criteria a tire service business works from, encoded here for illustration. This table is not an authoritative safety standard, and nothing here overrides a manufacturer's own guidance. The final authority is a trained technician with the tire off the rim and the inner liner under a light. The software exists to be consistent and explainable, not to be right on its own.

The four hundred lines that lied to us

The original pre-screen was written the way these things always get written. Someone had the criteria on a laminated sheet, transcribed them top to bottom, and each criterion became a branch that returned early.

def can_repair(t):
    if t["zone"] == "sidewall":
        return False
    if t["zone"] == "shoulder":
        return False
    if t["hole_mm"] > 6:
        return False
    if t.get("prior_repairs"):
        for r in t["prior_repairs"]:
            if abs(r["pos"] - t["pos"]) < 40:
                return False
    if t.get("tread_mm", 99) < 1.6:
        return False
    return True

Four failure modes, and they compound.

First, early return hides ordering. The moment one branch answers, none of the later branches run. That is fine when every branch produces the same verdict, and it is a trap the instant one branch produces a different one. Ours did: a later revision added a run-flat check that returned True for a specific construction, placed above the prior-repair loop by whoever merged it. A unit came in with a 5 mm injury 62 mm off the tread centreline on a 225-section tire, with an existing repair roughly 14 cm away around the circumference. The function said repairable. The technician who demounted it said no, twice, and was right both times.

Second, a boolean cannot express doubt. Look at t.get("tread_mm", 99). Someone defaulted a missing measurement to a value that guarantees the check passes. That is not a typo; it is the only thing you can do when your return type has two inhabitants and one of them means "go ahead." Missing data silently became permission.

Third, there is no provenance. The function returns False. Which criterion produced that? You can only find out by re-reading the code and mentally replaying it against the input. When a fleet coordinator asks why a $340 casing was condemned, "the system said so" is not an answer anyone accepts.

Fourth, there is no version. The criteria drift. Manufacturers publish revised guidance, internal practice tightens, a legal threshold changes. Six months later you cannot reproduce a past verdict, because the only copy of the old logic is in git history nobody wants to run.

Every one of those is a structural property of "criteria as control flow." You do not fix them by writing more careful conditionals. You fix them by making the criteria data.

The criteria a service business actually works from

Before any modelling, the plain-language version. Whether a punctured passenger or light-truck tire may be repaired is governed by a cluster of criteria that most of the trade agrees on, with variation at the edges:

The injury must fall in the crown — the central portion of the tread — not in the shoulder and never in the sidewall. Shoulder and sidewall flex through their entire duty cycle, and a patch there works loose.
The injury diameter has a ceiling. Six millimetres (about a quarter inch) is the common passenger-tire figure. Beyond that, the belt and body-ply damage is no longer something a patch spans.
The injury angle matters. A nail that entered at a steep angle travels laterally inside the casing, so the entry point on the tread and the actual damage path are not the same place. Steeply angled injuries are treated as larger than they measure.
A legitimate repair requires demounting. The tire comes off the rim, the inner liner gets inspected, the injury channel is filled and the inner surface is sealed with a patch. An externally inserted plug with the tire still on the wheel is a get-home measure, not a repair.
Repairs must not overlap, and there are limits on how many a casing may carry and how close together they may sit.
Run-flat construction and high speed ratings carry manufacturer-specific caveats; some brands decline repair entirely on certain lines.
Evidence that the tire was driven while deflated — a scuffed or wrinkled inner liner, rubber dust inside the casing — condemns it regardless of how small the puncture is.
Remaining tread depth and casing age can make the whole question moot.
A tire previously plugged from the outside without demounting has an unknown internal condition until somebody looks.

If you want the customer-facing version of the same material, we keep an explainer on how a proper demounted repair is performed, and a separate reference on reading what is moulded into the sidewall, which is where half of these inputs come from in the first place.

Notice how many of those clauses are about evidence rather than about geometry. That distribution is the single most important thing to carry into the data model.

Geometry: turning "crown" and "shoulder" into numbers

"In the crown" is not a machine-checkable predicate. We need a coordinate system.

We measure lateral offset in millimetres from the tread centreline, positive outboard, and we derive the crown boundary from tread width rather than section width. Section width is the moulded figure on the sidewall and includes the bulge; tread width is the part that actually meets the road. For a typical passenger fitment, tread width runs somewhere around 78–82 % of section width, and we store a per-fitment override when we have the real number from the manufacturer's data sheet.

The illustrative geometry we use in the examples below:

tread_width_mm = round(0.80 * section_width_mm) unless overridden
crown_half_width_mm = 0.5 * tread_width_mm - shoulder_band_mm
shoulder_band_mm = 12 for passenger fitments in this illustration

So a 225-section tire gets a 180 mm tread width, a 90 mm half-width, and a crown that extends to 78 mm either side of centre. An injury at 62 mm is comfortably inside. An injury at 79 mm is not. An injury at 78 mm is the interesting one, and we will come back to it.

Angular position around the circumference is a second coordinate, in degrees, with an arbitrary but recorded datum — we use the DOT stamp as zero, because it is the one landmark on the tire that is guaranteed to exist and guaranteed not to move. Arc distance between two points is then a wrap-aware computation on the rolling circumference, which we derive from the fitment. Anyone who has worked through the diameter math will recognize this; the load index and speed symbol reference we keep for technicians covers the sidewall codes those figures come from.

A typed record for the assessment, not a dict

Here is the input model. It is deliberately verbose about the difference between "we measured this" and "nobody wrote it down."

from __future__ import annotations

from dataclasses import dataclass, field
from enum import Enum, IntEnum
from typing import Callable, Optional, Sequence


class Zone(Enum):
    CROWN = "crown"
    SHOULDER = "shoulder"
    SIDEWALL = "sidewall"
    BEAD = "bead"


class Construction(Enum):
    STANDARD = "standard"
    RUN_FLAT = "run_flat"
    UNDETERMINED = "undetermined"


class PriorRepairKind(Enum):
    INTERNAL_PATCH_PLUG = "internal_patch_plug"
    EXTERNAL_PLUG_ONLY = "external_plug_only"
    UNIDENTIFIED = "unidentified"


@dataclass(frozen=True)
class Measured:
    """A number that remembers how it was obtained and how wrong it might be."""

    value: float
    tolerance: float          # half-width of the plausible band, same units
    method: str               # steel_rule | digital_caliper | visual_estimate

    def below(self, threshold: float) -> Optional[bool]:
        if self.value + self.tolerance < threshold:
            return True
        if self.value - self.tolerance >= threshold:
            return False
        return None           # band straddles the threshold; refuse to guess

    def above(self, threshold: float) -> Optional[bool]:
        flipped = self.below(threshold)
        return None if flipped is None else not flipped

The Measured type is doing real work. A tread-depth reading taken with a steel rule by a technician wearing gloves in an unheated bay in February has a tolerance around ±0.4 mm. A digital caliper on an injury diameter is closer to ±0.2 mm. When the plausible band crosses a threshold, below returns None, and that None will propagate all the way to the verdict rather than being rounded away. Three-valued logic starts at the measurement, not at the rule.

The rest of the record:

@dataclass(frozen=True)
class PriorRepair:
    angular_position_deg: float
    lateral_offset_mm: float
    kind: PriorRepairKind


@dataclass(frozen=True)
class Assessment:
    assessment_id: str
    captured_at: str                        # RFC 3339, always with offset
    section_width_mm: int
    rim_diameter_in: float
    tread_width_mm: Optional[int]           # override when known
    construction: Construction
    speed_symbol: Optional[str]
    zone: Optional[Zone]
    injury_diameter: Optional[Measured]
    injury_angle_deg: Optional[Measured]    # 0 = perpendicular to the surface
    lateral_offset: Optional[Measured]      # from the tread centreline
    angular_position_deg: Optional[float]
    tread_depth: Optional[Measured]
    dot_week: Optional[int]
    dot_year: Optional[int]
    liner_inspected: bool = False
    liner_shows_deflated_running: Optional[bool] = None
    prior_repairs: Sequence[PriorRepair] = field(default_factory=tuple)

Every field that a technician might fail to record is Optional. There are no sentinel defaults, no -1, no 99. If you take one idea from this article, take that one: the absence of a measurement must be representable, and it must be distinguishable from a measurement of zero.

Three verdicts, because two is a bug

class Verdict(Enum):
    REPAIRABLE = "repairable"
    REPLACE = "replace"
    INSUFFICIENT_EVIDENCE = "insufficient_evidence"

INSUFFICIENT_EVIDENCE is not an error state and it is not a failure of the engine. It is a legitimate, frequently correct answer that carries a payload: the list of inputs that would resolve it. Run the table across an illustrative assessment set and it lands on roughly a fifth of them, with about two-thirds of those resolving to a definite verdict once a single additional field arrives.

Two design commitments follow from having three values.

Fail closed on ambiguity that leans dangerous. Where an unknown could only make the situation worse, we do not return INSUFFICIENT_EVIDENCE; we return REPLACE. Evidence of running deflated is the clean example: if the liner was never inspected and the vehicle arrived on a tire that was flat at the roadside, the engine does not ask politely for more data, it condemns. The cost asymmetry is not close. A wrongly scrapped casing costs a few hundred dollars. A wrongly returned casing carries a belt separation down Stoney Trail at 100 km/h.

Never let a gap become a permission. There is exactly one rule in the table that can emit REPAIRABLE, it sits at the lowest precedence tier, and it fires only when every field it depends on is present and every exclusion has been evaluated to a definite False. Permission is the residue left after all the ways of saying no have been exhausted.

The table itself

This is the artifact that matters. It is reviewed by people who do not read Python, printed and marked up, and argued over. The code is downstream of it.

Rule	Tier	Condition	Verdict	Notes
R-010	EXCLUSION	Zone is sidewall or bead	REPLACE	No patch survives full-cycle flex there
R-020	EXCLUSION	Zone is shoulder	REPLACE	Belt edge region, excluded by practice
R-030	EXCLUSION	Lateral offset beyond crown half-width	REPLACE	Geometric restatement of R-020 for measured inputs
R-040	EXCLUSION	Injury diameter above 6.0 mm	REPLACE	Illustrative passenger ceiling
R-050	EXCLUSION	Injury angle above 25° from perpendicular	REPLACE	Damage path is longer than the entry hole suggests
R-060	EXCLUSION	Liner shows deflated running	REPLACE	Casing compromised independent of the puncture
R-070	EXCLUSION	Any prior repair within 40 cm arc of the new injury	REPLACE	Illustrative spacing floor; overlap is unconditional
R-080	EXCLUSION	Three or more prior internal repairs present	REPLACE	Cumulative casing load
R-090	EXCLUSION	Tread depth below 1.6 mm	REPLACE	Legal minimum reached; the repair question is moot
R-100	EXCLUSION	Casing age at or beyond 10 years from DOT date	REPLACE	Illustrative retirement horizon
R-200	REFERRAL	Construction is run-flat	REPLACE_UNLESS_OEM_PERMITS	Escalates to manufacturer guidance, not to the engine
R-210	REFERRAL	Speed symbol W, Y or above	REPLACE_UNLESS_OEM_PERMITS	Same escalation path
R-300	EVIDENCE	Prior external plug present, liner not inspected	INSUFFICIENT_EVIDENCE	Internal condition unknown until demounted
R-310	EVIDENCE	Tread depth not recorded	INSUFFICIENT_EVIDENCE	R-090 cannot be evaluated
R-320	EVIDENCE	Zone and lateral offset both absent	INSUFFICIENT_EVIDENCE	R-020 and R-030 both unevaluable
R-330	EVIDENCE	Injury diameter not recorded	INSUFFICIENT_EVIDENCE	R-040 cannot be evaluated
R-340	EVIDENCE	DOT date unreadable	INSUFFICIENT_EVIDENCE	R-100 cannot be evaluated
R-900	PERMIT	All exclusions definitely false, no gaps outstanding	REPAIRABLE	The residual case

Eighteen rows. The whole domain fits on one page, which is the point — the nested version was four hundred lines because control flow forces you to spell out the interactions between rules, whereas a table lets the evaluator handle interactions once, generically.

Rules as values

class Tier(IntEnum):
    EXCLUSION = 0
    REFERRAL = 1
    EVIDENCE = 2
    PERMIT = 3


Predicate = Callable[["Assessment"], Optional[bool]]


@dataclass(frozen=True)
class Rule:
    rule_id: str
    tier: Tier
    predicate: Predicate
    verdict: Verdict
    rationale: str                       # printed verbatim on the work order
    requires: tuple[str, ...] = ()       # fields whose absence makes it moot
    introduced_in: str = ""
    retired_in: Optional[str] = None

rationale is a string on the rule, not a lookup keyed by rule id in some other module. Anything that separates a rule from its explanation will drift; the explanation will describe a criterion that the predicate stopped checking two refactors ago, and nobody will notice because no test asserts on prose.

Predicate returns Optional[bool], which is the Kleene three-valued logic move. True means the rule fires. False means it definitely does not. None means we cannot tell from what we were given, and the evaluator must treat that as an outstanding gap rather than as a quiet False.

The predicates are ordinary named functions, not lambdas embedded in the table literal. That is a deliberate reversal of our first attempt. Lambdas in a table read beautifully for about a week and then become impossible to unit-test individually, impossible to name in a stack trace, and impossible to reuse across two rules that share a sub-condition.

CROWN_SHOULDER_BAND_MM = 12.0
MAX_INJURY_DIAMETER_MM = 6.0
MAX_INJURY_ANGLE_DEG = 25.0
MIN_TREAD_DEPTH_MM = 1.6
MIN_REPAIR_SEPARATION_MM = 400.0


def crown_half_width(a: Assessment) -> float:
    tread = a.tread_width_mm or round(0.80 * a.section_width_mm)
    return 0.5 * tread - CROWN_SHOULDER_BAND_MM


def in_sidewall_or_bead(a: Assessment) -> Optional[bool]:
    if a.zone is None:
        return None
    return a.zone in (Zone.SIDEWALL, Zone.BEAD)


def offset_outside_crown(a: Assessment) -> Optional[bool]:
    if a.lateral_offset is None:
        return None
    return a.lateral_offset.above(crown_half_width(a))


def injury_too_large(a: Assessment) -> Optional[bool]:
    if a.injury_diameter is None:
        return None
    return a.injury_diameter.above(MAX_INJURY_DIAMETER_MM)


def deflated_running_seen(a: Assessment) -> Optional[bool]:
    if a.liner_shows_deflated_running is True:
        return True
    if a.liner_inspected and a.liner_shows_deflated_running is False:
        return False
    return None

Read deflated_running_seen closely. It is the one predicate whose None we later convert to REPLACE rather than to a gap, and it is written so that a False is only reachable when somebody actually looked. You cannot clear that flag by leaving the field blank.

Arc separation, and why 14 cm is not 14 cm

Two repair sites 14 cm apart earns a permanent place in the fixture set, because it exposes a modelling error that is unusually easy to ship.

The first implementation compared angular positions directly and applied a degree threshold. That is wrong, because the same angular gap is a different physical distance on a 15-inch fitment than on a 20-inch one. What the criterion is really about is the amount of intact casing between two weakened points, which is arc length.

import math


def rolling_circumference_mm(a: Assessment) -> float:
    """Illustrative: rim diameter plus twice a nominal sidewall height."""
    rim_mm = a.rim_diameter_in * 25.4
    aspect = 0.55                              # placeholder for the example
    sidewall_mm = aspect * a.section_width_mm
    return math.pi * (rim_mm + 2.0 * sidewall_mm)


def arc_gap_mm(a: Assessment, other_deg: float) -> Optional[float]:
    if a.angular_position_deg is None:
        return None
    delta = abs(a.angular_position_deg - other_deg) % 360.0
    delta = min(delta, 360.0 - delta)           # shortest way round
    return (delta / 360.0) * rolling_circumference_mm(a)


def crowded_by_prior_repair(a: Assessment) -> Optional[bool]:
    if not a.prior_repairs:
        return False
    gaps = [arc_gap_mm(a, r.angular_position_deg) for r in a.prior_repairs]
    if any(g is None for g in gaps):
        return None
    return min(gaps) < MIN_REPAIR_SEPARATION_MM

Two bugs are fixed here and both were real. The % 360.0 followed by min(delta, 360 - delta) handles the wrap: a repair at 355° and an injury at 5° are 10° apart, not 350°. And returning None when any position is missing stops a partially-recorded repair history from producing a confident answer about spacing.

For a 225/55R17 in the example, rolling circumference lands near 1,940 mm. Two sites 14 cm apart occupy about 26° of arc and leave 140 mm of casing between them, well under the 400 mm illustrative floor. Verdict: REPLACE, cited to R-070. The nested version got this wrong not because the arithmetic was hard but because the run-flat branch above it had already returned.

An evaluator you can read in one sitting

@dataclass(frozen=True)
class Firing:
    rule_id: str
    verdict: Verdict
    rationale: str
    tier: Tier


@dataclass(frozen=True)
class Decision:
    verdict: Verdict
    table_version: str
    firings: tuple[Firing, ...]
    outstanding: tuple[str, ...]
    evaluated_at: str
    input_digest: str


def evaluate(a: Assessment, rules: Sequence[Rule], version: str,
             now: str, digest: str) -> Decision:
    fired: list[Firing] = []
    gaps: list[str] = []

    for rule in rules:
        outcome = rule.predicate(a)
        if outcome is True:
            fired.append(Firing(rule.rule_id, rule.verdict,
                                rule.rationale, rule.tier))
        elif outcome is None:
            gaps.extend(rule.requires or (rule.rule_id,))

    fired.sort(key=lambda f: (f.tier, f.rule_id))

    if fired and fired[0].tier <= Tier.REFERRAL:
        chosen = fired[0].verdict
    elif gaps:
        chosen = Verdict.INSUFFICIENT_EVIDENCE
    elif fired:
        chosen = fired[0].verdict
    else:
        chosen = Verdict.INSUFFICIENT_EVIDENCE      # empty table, fail closed

    return Decision(
        verdict=chosen,
        table_version=version,
        firings=tuple(fired),
        outstanding=tuple(sorted(set(gaps))),
        evaluated_at=now,
        input_digest=digest,
    )

Every rule is evaluated. Nothing short-circuits. That is the structural difference from the original, and it costs almost nothing — the whole table runs in single-digit microseconds, so there is no performance argument for early exit at this size.

The resolution order encodes a real policy judgement, so it is worth stating plainly rather than leaving it implicit in a comparison operator. A definite exclusion beats an outstanding gap: if the injury is in the sidewall, we do not need the tread depth to know the answer, and demanding it would waste a technician's time. A gap beats a permission: if anything at all is unresolved, permission is withheld. Referrals sit between exclusions and gaps because "the manufacturer has to answer this" is a definite finding about who decides, not an absence of information.

Provenance: every verdict names its parent rule

The Decision record carries firings — every rule that matched, in precedence order, with the rationale text attached. Rendering an explanation is then trivial, which is the whole point.

def explain(d: Decision) -> str:
    if d.verdict is Verdict.INSUFFICIENT_EVIDENCE and d.outstanding:
        missing = ", ".join(d.outstanding)
        return (f"Cannot decide under {d.table_version}. "
                f"Outstanding evidence: {missing}.")
    if not d.firings:
        return f"No criterion matched under {d.table_version}."
    head = d.firings[0]
    extra = len(d.firings) - 1
    tail = f" ({extra} further criterion matched)" if extra else ""
    return f"{head.verdict.value} per {head.rule_id}: {head.rationale}{tail}"

That string goes on the work order and into the fleet coordinator's export. It has settled more disputes than any amount of accuracy improvement, because the argument stops being "your system is wrong" and becomes "R-070 uses a 40 cm separation floor and we think that is too conservative for our application" — which is a productive conversation about a number in a table, not a defence of a codebase.

Reporting every match rather than just the decisive one also gives you a cheap monitoring signal. If R-050 has never once been the top firing but appears as a secondary match on 40 % of assessments, either the threshold is miscalibrated or technicians are entering a default angle. Both are worth knowing.

Checking the table, not just the code

Once criteria are data, you can interrogate the whole rule set as an object. Three checks run in CI on every change to the table.

Reachability. Enumerate a coarse grid over the input space and confirm each rule is the decisive firing for at least one cell. A rule that never decides anything is either dead or shadowed by a higher tier, and both deserve a look.

Conflict. Within a single tier, find cells where two rules fire with different verdicts. Across tiers this is expected and resolved by precedence; within a tier it is an authoring mistake, because tier membership is a claim that the rules are commensurable.

Coverage of the permit path. Confirm the grid contains at least one cell that reaches REPAIRABLE. An over-eager tightening of R-030 can make permission unreachable, and nothing fails loudly when it does. The engine simply says REPLACE to everything, which from the outside looks exactly like a bad week for punctures.

import itertools


def sweep(rules, version):
    zones = [Zone.CROWN, Zone.SHOULDER, Zone.SIDEWALL, None]
    diameters = [None, 2.0, 5.9, 6.1, 9.0]
    depths = [None, 1.4, 1.7, 6.0]
    decisive = {}
    conflicts = []

    for zone, dia, depth in itertools.product(zones, diameters, depths):
        a = fixture(zone=zone, diameter=dia, depth=depth)
        d = evaluate(a, rules, version, "1970-01-01T00:00:00Z", "grid")
        if d.firings:
            decisive.setdefault(d.firings[0].rule_id, 0)
            decisive[d.firings[0].rule_id] += 1
            top = [f for f in d.firings if f.tier == d.firings[0].tier]
            if len({f.verdict for f in top}) > 1:
                conflicts.append((zone, dia, depth,
                                  [f.rule_id for f in top]))

    unreached = [r.rule_id for r in rules if r.rule_id not in decisive]
    return decisive, unreached, conflicts

A coarse grid is not a proof. It catches the class of error that matters, which is a rule that can never win.

Properties worth asserting

Example-based tests pin down the cases you thought of. Properties pin down the shape of the function, and in a safety-adjacent classifier the shape is where the real invariants live.

from hypothesis import given, strategies as st


@given(delta=st.floats(min_value=0.01, max_value=20.0))
def test_monotone_in_injury_size(delta):
    """Making the injury bigger can never make it more permissible."""
    small = fixture(diameter=4.0)
    large = fixture(diameter=4.0 + delta)
    a = evaluate(small, RULES, TABLE_VERSION, NOW, "p1").verdict
    b = evaluate(large, RULES, TABLE_VERSION, NOW, "p2").verdict
    if a is not Verdict.REPAIRABLE:
        assert b is not Verdict.REPAIRABLE


@given(st.sampled_from(["tread_depth", "injury_diameter", "zone"]))
def test_erasure_never_grants_permission(name):
    """Deleting a field must not upgrade the verdict."""
    full = fixture(diameter=3.0, depth=5.0, zone=Zone.CROWN)
    thin = replace(full, **{name: None})
    before = evaluate(full, RULES, TABLE_VERSION, NOW, "e1").verdict
    after = evaluate(thin, RULES, TABLE_VERSION, NOW, "e2").verdict
    if before is not Verdict.REPAIRABLE:
        assert after is not Verdict.REPAIRABLE
    else:
        assert after in (Verdict.REPAIRABLE, Verdict.INSUFFICIENT_EVIDENCE,
                         Verdict.REPLACE)


@given(st.integers(min_value=0, max_value=5000))
def test_determinism_under_rule_order(seed):
    """Verdict must not depend on the order rules sit in the tuple."""
    rng = random.Random(seed)
    shuffled = list(RULES)
    rng.shuffle(shuffled)
    a = fixture(diameter=5.0, depth=4.0, zone=Zone.CROWN)
    left = evaluate(a, RULES, TABLE_VERSION, NOW, "d1")
    right = evaluate(a, tuple(shuffled), TABLE_VERSION, NOW, "d2")
    assert left.verdict is right.verdict
    assert [f.rule_id for f in left.firings] == \
           [f.rule_id for f in right.firings]

That third property is the one that found a genuine defect. An early version sorted firings by tier alone, so two exclusions in the same tier resolved in whatever order the tuple happened to hold — stable, but dependent on authoring sequence. The verdict was identical either way, yet the cited rule changed, which meant the explanation printed on two identical work orders could differ. Sorting by (tier, rule_id) fixed it. Monotonicity and erasure-safety, by contrast, have never failed; they are regression armour for the day somebody adds a clever optimisation.

Golden cases, kept in a format the bay can read

Properties do not replace worked examples, because the examples are how non-programmers review the logic. Ours live in YAML, one file, reviewed by whoever is running the service floor that quarter.

- name: clean_crown_nail
  note: routine gravel-season puncture, everything measured
  input:
    zone: crown
    section_width_mm: 215
    injury_diameter: {value: 4.2, tolerance: 0.2, method: digital_caliper}
    injury_angle_deg: {value: 6.0, tolerance: 3.0, method: visual_estimate}
    lateral_offset: {value: 41.0, tolerance: 2.0, method: steel_rule}
    tread_depth: {value: 6.4, tolerance: 0.4, method: steel_rule}
    liner_inspected: true
    liner_shows_deflated_running: false
    dot_week: 22
    dot_year: 2022
  expect:
    verdict: repairable
    cited: R-900

- name: shoulder_boundary_exact
  note: offset lands precisely on the computed crown limit
  input:
    zone: crown
    section_width_mm: 225
    lateral_offset: {value: 78.0, tolerance: 1.5, method: steel_rule}
    injury_diameter: {value: 3.1, tolerance: 0.2, method: digital_caliper}
    tread_depth: {value: 7.0, tolerance: 0.4, method: steel_rule}
    liner_inspected: true
    liner_shows_deflated_running: false
  expect:
    verdict: insufficient_evidence
    outstanding: [lateral_offset]

- name: two_repairs_fourteen_centimetres
  note: prior repair too close around the circumference
  input:
    zone: crown
    section_width_mm: 225
    rim_diameter_in: 17
    angular_position_deg: 12.0
    prior_repairs:
      - {angular_position_deg: 38.0, lateral_offset_mm: 30.0,
         kind: internal_patch_plug}
  expect:
    verdict: replace
    cited: R-070

The runner is fifteen lines and does nothing clever. What earns its keep is the note field, which forces whoever adds a case to say why it exists. Half of our regressions have been caught by somebody reading a note during review and saying that is not what we do any more.

The boundary case that changed our mind about rounding

Take shoulder_boundary_exact above. A 225-section fitment gives a crown half-width of exactly 78.0 mm. The technician records a lateral offset of 78.0 mm using a steel rule with a ±1.5 mm tolerance. Is the injury in the crown or the shoulder?

The honest answer is that we do not know, and the plausible band spans both. Measured.above(78.0) returns None because 76.5 < 78.0 <= 79.5. R-030 contributes a gap rather than a firing, and the verdict is INSUFFICIENT_EVIDENCE with lateral_offset named as the outstanding item. The remedy is a caliper measurement, which takes about thirty seconds and collapses the tolerance to ±0.2 mm.

We debated failing closed to REPLACE here instead, on the theory that the safe default should apply. We did not, and the reasoning is worth spelling out because it is the one place we deliberately do not fail closed. A REPLACE verdict is terminal — the casing goes in the scrap pile and nobody re-measures. INSUFFICIENT_EVIDENCE is a request that costs half a minute and produces a defensible answer either way. Failing closed is correct when better evidence is unobtainable or when the unknown is itself a danger signal; it is not correct when the unknown is simply a measurement nobody has bothered to take yet. Those are different situations and collapsing them wastes casings.

Note also the half-open interval. above uses >= on the lower comparison, so an offset of exactly 78.0 mm with zero tolerance would be treated as outside the crown. Boundary inclusivity is a decision, it should be written down in the table, and it should have a golden case pinning it. Ours does.

Missing tread depth: a gap with a name

The third nasty fixture is the simplest and the most common. A technician records everything about the injury and never gets a tread-depth reading, because the vehicle was on the hoist for an oil change and the tire never came off.

R-310 fires — tread_depth is None — contributing the outstanding field. No exclusion has fired definitely, so the verdict is INSUFFICIENT_EVIDENCE and the explanation reads: Cannot decide under repairability/2026.02.1. Outstanding evidence: tread_depth.

Compare that with the original code, where t.get("tread_mm", 99) turned an unmeasured tire into one with 99 mm of tread. The difference is not that the new engine is smarter. It is that the new engine has somewhere to put "I do not know," and the old one did not, so the unknown had to masquerade as something.

This shows up disproportionately in work performed by our mobile service unit, where the assessment happens in a parking lot rather than a bay. Mobile assessments produce roughly twice the INSUFFICIENT_EVIDENCE rate of in-bay ones, and that is not a defect in the software — it is the software correctly reporting that a driveway in a February wind is a worse measurement environment than a lift. The coverage map for that unit determines how often it happens.

Versioning, so last year's verdict can be replayed

Criteria change. When they do, every decision already issued was issued under the old table, and you need to be able to say so.

@dataclass(frozen=True)
class RuleSet:
    version: str                 # e.g. repairability/2026.02.1
    effective_from: str
    effective_to: Optional[str]
    rules: tuple[Rule, ...]

    def digest(self) -> str:
        payload = "|".join(
            f"{r.rule_id}:{r.tier}:{r.verdict.value}:"
            f"{r.predicate.__name__}:{r.rationale}"
            for r in self.rules
        )
        return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:16]


REGISTRY: dict[str, RuleSet] = {}


def ruleset_in_force(at: str) -> RuleSet:
    matches = [rs for rs in REGISTRY.values()
               if rs.effective_from <= at
               and (rs.effective_to is None or at < rs.effective_to)]
    if len(matches) != 1:
        raise LookupError(f"{len(matches)} rule sets in force at {at}")
    return matches[0]

Three properties fall out. Persisted decisions store table_version, so replay is a registry lookup rather than an archaeology expedition. The digest covers predicate names and rationale text, which means renaming a predicate or editing an explanation forces a version bump — annoying by design, because a changed explanation is a changed decision from the reader's point of view. And ruleset_in_force raising on ambiguity means a botched effective-date edit fails at startup instead of silently picking whichever set the dict happened to yield first.

The migration test is the payoff. Before a new table goes live, we replay the last twelve months of stored assessments under both versions and diff the verdicts.

def replay_diff(records, old: RuleSet, new: RuleSet):
    changed = []
    for rec in records:
        a = deserialize(rec["input"])
        before = evaluate(a, old.rules, old.version, rec["at"], rec["digest"])
        after = evaluate(a, new.rules, new.version, rec["at"], rec["digest"])
        if before.verdict is not after.verdict:
            changed.append({
                "assessment_id": a.assessment_id,
                "from": before.verdict.value,
                "to": after.verdict.value,
                "was_cited": before.firings[0].rule_id if before.firings else None,
                "now_cited": after.firings[0].rule_id if after.firings else None,
            })
    return changed

The first time we ran this against a proposed revision, it flipped 11 % of historical verdicts from REPLACE to REPAIRABLE. That was not a bug in the new table; it was an accurate report that we had been over-conservative on injury angle for a year. Knowing the magnitude before shipping changed how we communicated the revision to fleet customers, which is worth more than the code.

The decision log

Decisions are appended, never updated. A correction is a new record referencing the one it supersedes.

{
  "decision_id": "dec_01HQ4R9K2",
  "assessment_id": "asm_2026_08_10_0113",
  "supersedes": null,
  "verdict": "replace",
  "table_version": "repairability/2026.02.1",
  "table_digest": "9f2a7c1e04b3d8aa",
  "firings": [
    {"rule_id": "R-070", "tier": 0,
     "rationale": "Prior repair within the illustrative 40 cm arc floor"}
  ],
  "outstanding": [],
  "input_digest": "sha256:4b1d...",
  "evaluated_at": "2026-08-10T09:41:22-06:00",
  "engine_build": "rules-engine 0.9.3",
  "actor": "prescreen-service"
}

input_digest is a hash over the canonicalised assessment, which lets you prove that a replay used identical inputs without storing a second copy. engine_build is separate from table_version because the evaluator and the criteria change independently, and you will eventually have a defect that lives in one and not the other.

We keep decision records for the life of the casing plus two years. Retention is not a compliance box here so much as the only way to answer "has this casing been repaired before, and where" when it comes back on a different vehicle eighteen months later — which happens constantly on the fleet side of the business, where wheels and tires migrate between units.

Where Calgary actually presses on the model

Some of this is genuinely local, and it changes the numbers rather than the structure.

Gravel season is the obvious one. Chip-seal work and the winter aggregate that lingers into spring produce a puncture wave from roughly April into June, and the injuries skew small, shallow, and squarely in the crown — exactly the population where a decision table earns its money, because volume plus a clear-cut criterion is where human inconsistency shows up. Two technicians will not disagree about a sidewall gash. They will absolutely disagree about a 5.8 mm injury measured with a rule.

Changeover volume is the second. The compression of seasonal work into a few weeks each spring and fall — the seasonal changeover service is the single busiest thing the business does — means a large number of tires get inspected in a short window by people who are tired. Consistency under fatigue is precisely what you buy with a rule table, and it is also when the pre-screen's INSUFFICIENT_EVIDENCE rate climbs, which is a useful staffing signal in its own right.

Road salt and brine change what "prior repair" evidence looks like. Corrosion around the bead seat and valve area can obscure or mimic damage, and a patch applied three seasons ago may sit under a layer of deposit. That is a data-capture problem, not a rules problem, but it is why liner_inspected is a separate boolean from liner_shows_deflated_running — "we looked and saw nothing" and "we could not see" are different states.

Then there is the fleet population. Units running Deerfoot and Stoney Trail accumulate distance fast, so casing age and remaining depth interact with the repair question more often than they do on a family vehicle that does 12,000 km a year. A casing that is technically repairable but has 3 mm left is a different economic proposition, and the engine deliberately does not model that — economics belong to whoever is paying, and mixing them into a safety table is how safety tables get quietly relaxed. What we do instead is emit the verdict plus the measured depth, and let the commercial service side make the money argument separately. Seasonal fitment choice interacts too, since dedicated winter rubber spends half the year in storage and comes back with a service history the pre-screen has to reconstruct.

One more operational note: after any repair the wheel assembly goes back on the balancer, because a patch and the material removed to prepare for it change the mass distribution. That is downstream of the engine entirely, but it is the reason our work-order template links the verdict to the balancing step rather than treating the repair as the end of the job.

Cost, placement, and what the engine is not

The evaluator is cheap. Eighteen rules over a frozen dataclass runs in a few microseconds; we have never profiled it because there has never been a reason to. If your rule set grows into the thousands you would index predicates by the fields they read and skip the ones whose inputs are absent, but at this scale that optimisation would be pure complexity.

The expensive part is data capture, and it is expensive in minutes rather than milliseconds. Getting a caliper reading, a DOT date, and a liner inspection onto a record adds two or three minutes per tire during the busiest weeks of the year. That is the actual cost of the system, and it is worth being honest that a rules engine does not reduce it — it relocates it, from an argument after the fact to a measurement before it.

The engine also sits in front of a human, never behind one. It runs at intake and on fleet pre-screens, producing a recommendation with a citation. It does not gate the technician. If R-040 says replace and the technician demounts the tire and finds a 4 mm injury rather than the 7 mm somebody eyeballed in the lane, the technician's finding wins and the assessment gets corrected, which produces a new decision record superseding the old one. General background on how any of this looks from the driver's side lives in our tire-safety primer, and the roadside cases that skip the pre-screen entirely go through emergency service dispatch.

What we would do differently

Write the table before the evaluator. We did it the other way and spent a week retrofitting a data structure onto assumptions the code had already baked in. The markdown table in this article existed as a printed sheet with pen marks on it before a line of Python was written the second time round, and that ordering was worth more than any refactor.

Do not build a DSL. Our first design had a small expression language so that criteria could be edited without a deploy. It was seductive and it was wrong: we ended up with an interpreter, a parser, an error-reporting story, and a testing story, all to avoid a five-minute deploy. Predicates as plain named functions, versioned in the same repository as everything else, has cost us nothing.

Version from the first commit. We added table_version in month four and have a gap in the record where earlier decisions cannot be replayed. There is no way to backfill that. It costs eight lines to do on day one.

Resist the fourth verdict. There has been steady pressure to add something like REPAIRABLE_WITH_CAVEAT. Every proposed instance turned out to be either a referral (the manufacturer decides) or an economic judgement (the owner decides), and both belong outside the safety classification. Three values is not a limitation; it is the discipline.

Treat the explanation as an interface. As soon as fleet coordinators start reading rationale strings, those strings become a published surface. Edit one and somebody notices. That is a feature, and it is why the digest covers them.

Questions we get asked

Why not an off-the-shelf rules engine? Eighteen rules over one flat record does not justify a Rete network, a separate language, or a runtime whose evaluation semantics we would have to explain to a technician. The list-of-predicates approach fits in a file, is trivially testable, and has no dependency to upgrade. Reach for the heavy tooling when rules number in the hundreds and are authored by people outside the engineering group.

Why not learn the rules from historical outcomes? Two reasons. The training signal is contaminated — historical verdicts were produced by the buggy nested code and by inconsistent human judgement — and a model cannot cite R-070. Explainability here is not a nice-to-have; it is most of the product's value. There is a defensible role for vision models in measuring injury diameter from a photograph, feeding the table better inputs. That is a perception problem, and it should stay separate from the decision.

How do manufacturer-specific caveats fit? They are the referral tier. R-200 and R-210 do not decide anything; they route to a human with the manufacturer's documentation. Attempting to encode every brand's line-by-line position on run-flat repair would produce a table that is wrong the moment a bulletin is revised, and wrong in a way nobody notices for months.

What happens when a technician disagrees with the verdict? The technician wins, and the disagreement is recorded with a reason code. We review overrides quarterly. A rule that is overridden 30 % of the time is a mis-specified rule, and the override log is the highest-value dataset the system produces — better than any accuracy metric, because it points at the specific criterion under dispute.

Does the table get bigger over time? Slower than you would expect. It went from fourteen rules to eighteen in two years. Most requested additions turn out to be a threshold change to an existing rule rather than a new criterion, which is a good sign that the decomposition is roughly right.

Where do the input values come from? Mostly a tablet form in the bay, with the fitment fields pre-populated from the size code read off the sidewall. The parsing of that code is its own small problem, and getting it wrong poisons the geometry — which is why the crown half-width calculation carries an override field rather than trusting a derived tread width when a real figure exists.

Where the engine's authority ends

The table does not know that the casing in front of you was sitting in a puddle of coolant, or that the inner liner has a wrinkle pattern the technician has seen four times and associates with a particular failure, or that this specific fleet runs a load profile the criteria were never written for. It knows eighteen things and it knows them consistently, which is precisely the value: it removes the variance that comes from the fourteenth tire of a Saturday in November, and it leaves the judgement that comes from ten years of demounting tires exactly where it belongs.

That division is the design. Encode what is codifiable, refuse to guess at what is not, name every unknown out loud, and make every answer traceable to the criterion that produced it. The nested version failed not because its criteria were wrong — most of them were fine — but because control flow is a terrible medium for a rule set that has to be reviewed, explained, and replayed. Data is a better medium. The evaluator is forty lines and has not needed to change in a year, while the table has been revised five times, which is exactly the ratio you want.

If you are building something in this shape, the test I would apply is narrow: can a domain expert who does not read your language review the criteria, and can you reproduce any past answer exactly? If either is a no, the criteria are still hiding in the code.

Building a Weather-Triggered Tire Advisory Pipeline: Ingesting Environment Canada Data to Drive Maintenance Alerts for Calgary Drivers

KMJ Tire Calgary — Sun, 09 Aug 2026 16:11:23 +0000

Building a Weather-Triggered Tire Advisory Pipeline: Ingesting Environment Canada Data to Drive Maintenance Alerts for Calgary Drivers

I run the technical side of a small Calgary tire business, and for the past two winters I have been iterating on a pipeline that watches Environment and Climate Change Canada (ECCC) open data and decides, automatically, when a weather situation is relevant enough to tires that a driver should hear about it. Not "it might snow" — everyone in Calgary owns a window. The pipeline exists for the narrower, more actionable events: the first sustained cold stretch that makes winter rubber matter, a chinook swing that silently pulls four or five PSI out of every tire in the city, freezing rain, summer hail cells, and the deep-cold snaps where TPMS dashboards light up across town for reasons that are physics, not punctures.

This is a design writeup, not a product pitch. I am going to cover the ECCC data surfaces worth ingesting, the normalized schema I landed on after two bad first drafts, the advisory rule catalogue with actual thresholds, the hysteresis and deduplication machinery that stops the system from flapping, how I backtested rule precision and recall against past seasons, and the delivery layer with rate limiting and audit logging. All numeric thresholds shown are design examples from my configuration — tune them against your own data before trusting them.

Why Calgary Weather Is a Legitimately Hard Input

Calgary sits at roughly 1,045 metres elevation on the dry side of the Rockies, and its weather has three properties that make naive alerting embarrassing.

First, chinooks. Warm, dry downslope winds can raise the air temperature 15 to 25°C within hours. Calgary averages somewhere in the range of 20 to 30 chinook days per winter depending on how you count them. A rule that fires on "temperature crossed 0°C" will fire constantly from November through March and train every recipient to ignore it.

Second, variance around the seasonal transition. The historical median for the first hard freeze lands in early-to-mid October, but the spread is wide: I have replayed years where the first sustained sub-7°C stretch arrived in late September and years where it held off until November. A calendar-based reminder ("it is October 15, think about winter rubber") is wrong by weeks in either direction more often than it is right. The 7°C figure itself is the industry-standard crossover point where winter tread compounds begin outperforming all-season compounds — that is the physical basis for the winter tire timing guidance we publish, and it is the number the pipeline hunts for in forecast data.

Third, hail. Calgary sits inside what meteorologists informally label hailstorm alley. Convective cells between June and September produce short-notice severe weather warnings, and the tire-relevant advice ("get the vehicle under cover; inspect sidewalls afterward") has a useful lead time measured in tens of minutes. That pushes part of the architecture toward push-based ingestion rather than polling.

So the input signal is genuinely volatile, the false-positive cost is recipient fatigue, and the false-negative cost is a driver on all-seasons in the first -15°C week. Those constraints shaped everything below.

The Three ECCC Data Surfaces and When to Use Each

ECCC exposes its open data through several distinct mechanisms, and the pipeline uses three of them for different jobs.

GeoMet OGC APIs for structured queries

The GeoMet platform (api.weather.gc.ca) serves OGC API - Features collections over plain HTTPS with JSON responses. The collections I lean on:

climate-daily — quality-controlled historical daily observations (max/min/mean temperature, precipitation) per station. This is the backbone of backtesting.
climate-stations — station metadata, used once to pin the Calgary International Airport station (climate identifier 3031094 in my configuration) as the canonical observation source.
CAP alert collections — active weather alerts as GeoJSON features with polygon geometry, which lets you do a point-in-polygon test against a Calgary coordinate instead of string-matching region names.

A representative request for historical dailies:

GET https://api.weather.gc.ca/collections/climate-daily/items?
    CLIMATE_IDENTIFIER=3031094
    &datetime=2023-09-01/2024-04-30
    &sortby=LOCAL_DATE
    &limit=1000
    &f=json

Paginate with offset, respect the numberMatched field, and cache aggressively — historical dailies are immutable once quality control settles, so I store them locally and never re-fetch a closed month.

Citypage XML for the human-aligned forecast

The citypage weather product is the same forecast Calgarians see on official channels, published as XML per site under dd.weather.gc.ca/citypage_weather/. Calgary is site s0000047 in Alberta's directory. The payload includes current conditions, seven-day forecast periods with textual summaries and numeric highs/lows, and issue timestamps.

Why use a legacy-feeling XML product when model data exists? Because advisory text ultimately reaches humans, and the citypage forecast is the forecast a recipient can verify against every other weather surface in their life. If my pipeline says "sustained cold arriving Thursday" and their phone's weather app disagrees, trust erodes. Anchoring rules to the public forecast keeps the system's claims checkable.

MSC Datamart AMQP for push latency

The Datamart also publishes an AMQP 0-9-1 message feed (the xpublic exchange on dd.weather.gc.ca, anonymous credentials, topic-based routing) announcing every new file the moment it lands. The Sarracenia project wraps this, but a plain pika consumer works fine for a narrow subscription. I subscribe to two topic patterns: the Alberta citypage updates and the CAP alert directory.

import pika

AMQP_URL = "amqps://anonymous:anonymous@dd.weather.gc.ca:5671"
TOPICS = [
    "v02.post.citypage_weather.xml.AB.#",
    "v02.post.alerts.cap.#",
]

def start_consumer(on_announcement):
    params = pika.URLParameters(AMQP_URL)
    conn = pika.BlockingConnection(params)
    ch = conn.channel()
    q = ch.queue_declare(queue="", exclusive=True, auto_delete=True)
    for topic in TOPICS:
        ch.queue_bind(exchange="xpublic",
                      queue=q.method.queue,
                      routing_key=topic)
    ch.basic_consume(queue=q.method.queue,
                     on_message_callback=on_announcement,
                     auto_ack=False)
    ch.start_consuming()

Each announcement message carries the path of the new file; the consumer fetches it over HTTPS, hands it to the parser, and acknowledges. The division of labour that emerged: AMQP for anything latency-sensitive (alerts, forecast refreshes), scheduled HTTPS polling as a belt-and-suspenders fallback every 30 minutes, and GeoMet queries for historical and station data. If the AMQP connection drops overnight — it happens — the poller means the worst case is a half-hour-stale forecast, not a silent outage.

Normalizing Everything Into One Typed Schema

The first draft of this system passed raw parsed XML dictionaries around, and every rule reimplemented unit handling and missing-value checks. The second draft fixed that with a small set of typed models that every ingestion path must produce. Rules only ever see normalized records.

from dataclasses import dataclass
from datetime import datetime, date
from enum import Enum
from typing import Optional

class Source(Enum):
    CITYPAGE = "citypage"
    GEOMET_DAILY = "geomet_daily"
    CAP_ALERT = "cap_alert"

@dataclass(frozen=True)
class ForecastPeriod:
    site_id: str              # e.g. "s0000047"
    issued_at: datetime       # UTC, from the feed's own timestamp
    period_start: date        # local Calgary date the period covers
    is_overnight: bool
    temp_high_c: Optional[float]
    temp_low_c: Optional[float]
    pop_percent: Optional[int]        # probability of precipitation
    condition_codes: frozenset[str]   # normalized: {"freezing_rain", ...}
    text_summary: str
    source: Source

@dataclass(frozen=True)
class Observation:
    station_id: str
    observed_at: datetime
    temp_c: Optional[float]
    wind_kmh: Optional[float]
    station_pressure_kpa: Optional[float]
    source: Source

@dataclass(frozen=True)
class HazardAlert:
    cap_id: str               # CAP message identifier, natural dedup key
    event_kind: str           # normalized: "freezing_rain", "hail", ...
    severity: str             # CAP severity: minor/moderate/severe/extreme
    onset: Optional[datetime]
    expires: Optional[datetime]
    covers_calgary: bool      # result of point-in-polygon test
    raw_headline: str

Two normalization decisions earned their keep:

Condition codes are a controlled vocabulary. Citypage text summaries are free-form English ("Periods of freezing drizzle changing to snow near noon"). A mapping layer reduces each summary to a set of canonical codes — freezing_rain, freezing_drizzle, snow, rain, thunderstorm, hail_risk — via ordered keyword rules with an explicit unmapped bucket that gets logged and reviewed weekly. Rules never regex the prose directly. When ECCC rewords a summary format (it has happened), the blast radius is one mapping table, not every rule.

Timestamps are stored in UTC, bucketed in local time. Forecast periods and advisory windows are meaningful to humans in America/Edmonton local time, including the daylight-saving transitions. Everything persists as UTC; every rule that reasons about "days" converts through the timezone explicitly. The one early bug I shipped in this area — a winter-window evaluation that shifted a day at the November DST boundary — is why the conversion now lives in exactly one function with a regression test pinned to the 2023 transition dates.

The persistence layer is PostgreSQL. Trimmed DDL for the two hot tables:

CREATE TABLE forecast_snapshot (
    id              BIGSERIAL PRIMARY KEY,
    site_id         TEXT NOT NULL,
    issued_at       TIMESTAMPTZ NOT NULL,
    period_start    DATE NOT NULL,
    is_overnight    BOOLEAN NOT NULL,
    temp_high_c     NUMERIC(4,1),
    temp_low_c      NUMERIC(4,1),
    pop_percent     SMALLINT,
    condition_codes TEXT[] NOT NULL DEFAULT '{}',
    text_summary    TEXT NOT NULL,
    ingested_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
    UNIQUE (site_id, issued_at, period_start, is_overnight)
);

CREATE TABLE advisory_event (
    id               BIGSERIAL PRIMARY KEY,
    rule_id          TEXT NOT NULL,
    dedup_key        TEXT NOT NULL UNIQUE,
    fired_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
    window_start     DATE,
    window_end       DATE,
    evidence         JSONB NOT NULL,
    state            TEXT NOT NULL DEFAULT 'pending'
        CHECK (state IN ('pending','delivered','suppressed','expired'))
);

The UNIQUE constraint on forecast_snapshot makes re-ingestion of the same issuance a no-op (ON CONFLICT DO NOTHING), which matters because the AMQP consumer and the fallback poller will regularly both fetch the same file. The evidence JSONB column stores the exact snapshot rows a rule saw when it fired — indispensable later when a recipient asks why they received something, and equally useful when they ask why they did not.

The Advisory Rule Catalogue

Each rule is a pure function from (normalized data, rule state) to (optional advisory, new rule state). The catalogue, with my current design-example thresholds:

Rule ID	Trigger summary	Arm threshold (design example)	Disarm / reset	Season gate
`winter_window`	First sustained sub-7°C forecast stretch	≥5 of next 7 daily highs < 7°C	Re-arms next Aug 1	Sep 1 – Dec 15
`chinook_swing`	Large fast temperature rise or reversal	≥18°C swing within 36 h in forecast or obs	72 h cooldown	Oct 15 – Apr 15
`pressure_drop`	Cold arrival implies meaningful PSI loss	Forecast mean drops ≥15°C vs trailing 7-day obs mean	96 h cooldown	Year-round
`freezing_rain`	Freezing rain / drizzle in forecast or CAP	Condition code present with PoP ≥ 60%, or CAP severity ≥ moderate	Clears when window passes	Year-round
`hail_risk`	Severe thunderstorm watch/warning covering Calgary	CAP event mapped to hail-capable kinds	Clears on CAP expiry	May 1 – Sep 30
`deep_cold`	Extreme cold with TPMS side-effects	≥2 consecutive forecast lows ≤ -25°C	Ends when forecast lows > -20°C (hysteresis gap)	Nov 1 – Mar 31

Season gates are not cosmetic. They cut the evaluation surface — hail_risk simply cannot fire in January — which both prevents absurd advisories and shrinks the false-positive space the backtests have to measure.

A few of these rules deserve a closer look, because the interesting engineering hides in their edge cases.

The winter-window rule and its off-by-one-season traps

The intent: detect the first stretch of the autumn where the forecast says daytime highs will sit below 7°C for most of a week, because that is when compound physics starts favouring winter tread. Drivers running all-weather rubber (the mountain-snowflake-rated year-round category) get a differently worded advisory than drivers on pure all-seasons, whose compound is the one actually going hard below the crossover.

The naive implementation — "count forecast days with high < 7" — flapped badly in my 2023 replay. A single chinook-warmed Wednesday in an otherwise cold week resets the count, the advisory un-fires, then re-fires Friday. Three fixes:

Quorum, not streak. Require 5 of 7, not 7 consecutive. Chinooks poke one-day holes in cold stretches constantly; a quorum tolerates them.
Fire-once latching. Once winter_window fires, it stays fired for the season. There is no natural "un-trigger" for "winter is coming" — the state resets on August 1.
Persistence requirement. The quorum must hold across two consecutive forecast issuances at least 12 hours apart. A single aggressive model run at 4 a.m. that walks back by the afternoon issuance never reaches recipients.

def eval_winter_window(periods: list[ForecastPeriod],
                       state: RuleState) -> tuple[Advisory | None, RuleState]:
    if state.latched or not in_season(date.today(), SEP_1, DEC_15):
        return None, state
    week = daytime_periods(periods)[:7]
    cold = [p for p in week if p.temp_high_c is not None
            and p.temp_high_c < 7.0]
    if len(cold) < 5:
        return None, state.observed(False)
    if not state.held_for(hours=12):        # persistence across issuances
        return None, state.observed(True)
    advisory = Advisory(
        rule_id="winter_window",
        window=(week[0].period_start, week[-1].period_start),
        evidence={"cold_days": len(cold),
                  "highs": [p.temp_high_c for p in week]},
    )
    return advisory, state.latch()
</code-omitted-helpers-are-boring>

(That closing pseudo-tag is a joke; the helpers are ordinary date filters.) The practical effect of the three fixes in the 2023-24 replay: fire count dropped from 6 to 1, and the single firing landed on October 11 — four days before the first snowfall that season reached the ground. Design-example replay figures, but they sold me on latching.

One more subtlety: the rule reads forecast data, but the season's observed dailies from climate-daily are what the backtest later uses to decide whether the firing was "correct." Keeping those two roles separate in code — forecast triggers, observations judge — kept the evaluation honest.

Chinooks, the ideal gas law, and where the PSI actually goes

The pressure_drop and chinook_swing rules share a physical core, so let me do the worked math once, properly. Tire pressure follows the ideal gas approximation well enough for advisory purposes: at fixed volume and air mass, absolute pressure scales with absolute temperature.

P2_abs = P1_abs × (T2_K / T1_K)

The trap everyone hits: gauges read gauge pressure, and the scaling law applies to absolute pressure. In Calgary the distinction is bigger than at sea level, because at ~1,045 m the ambient pressure is around 88.5 kPa ≈ 12.8 PSI rather than 14.7.

Worked design example. A driver sets tires to 35.0 PSI (gauge) on a mild chinook afternoon at +5°C. A cold front ends the chinook and the overnight temperature reaches -25°C — an entirely ordinary Calgary reversal.

T1 = 5°C   = 278.15 K
T2 = -25°C = 248.15 K

P1_abs = 35.0 + 12.8            = 47.8 PSI (absolute)
P2_abs = 47.8 × (248.15/278.15) = 42.6 PSI (absolute)
P2_gauge = 42.6 − 12.8          = 29.8 PSI

Loss ≈ 5.2 PSI over a 30°C drop  →  ~1 PSI per 5.8°C

That is the familiar rule of thumb — roughly 1 PSI per 5-6°C — derived rather than asserted. Note what it means in practice: a tire that read a healthy 35 in the warm reads under 30 in the cold, without any leak, and 29.8 is below many door-placard specs. The vehicle placard and the sidewall marking are different numbers with different meanings, which trips up enough people that we wrote a plain-language sidewall marking explainer for exactly this confusion; the placard is the inflation target, the sidewall figure is a maximum.

The pressure_drop rule turns the derivation into a trigger: compute the trailing 7-day mean observed temperature from climate-daily plus recent hourly observations, compare against the forward 3-day forecast mean, and if the drop is ≥15°C, emit an advisory whose body includes the computed estimated PSI loss for a placard-typical inflation, clearly labelled as an estimate. Recipients respond much better to "expect roughly 3-4 PSI lower readings by Thursday" than to "cold weather affects tire pressure," which is weather-app wallpaper.

-- Trailing observed mean vs. forward forecast mean (design example)
WITH trailing AS (
  SELECT AVG(mean_temp_c) AS obs_mean
  FROM climate_daily_local
  WHERE station_id = '3031094'
    AND local_date >= CURRENT_DATE - INTERVAL '7 days'
),
forward AS (
  SELECT AVG((temp_high_c + temp_low_c) / 2.0) AS fc_mean
  FROM latest_forecast
  WHERE period_start BETWEEN CURRENT_DATE + 1
                         AND CURRENT_DATE + 3
)
SELECT obs_mean, fc_mean,
       (obs_mean - fc_mean) AS drop_c,
       (obs_mean - fc_mean) >= 15.0 AS should_consider_firing
FROM trailing, forward;

should_consider_firing, not should_fire — the SQL is a candidate filter; hysteresis state in the application layer makes the final decision.

The chinook-specific angle deserves a sentence more. A chinook rise also matters: air warms, pressure climbs back, and a driver who topped up during the cold snap is now a couple PSI over placard, then under again when the chinook collapses. The chinook_swing advisory therefore talks about re-checking after the swing settles rather than chasing the gauge mid-swing, and it links the general inflation-habits material on pressure-aware tire care rather than urging immediate action. Advising inaction at the right moment is an underrated advisory type.

Freezing rain and hail: the CAP-driven rules

These two rules are structurally simpler because ECCC has already done the meteorology; the pipeline's job is filtering and framing. CAP alert XML arrives via the AMQP subscription within seconds of publication. Processing steps:

Parse the CAP envelope; extract event type, severity, urgency, onset/expiry, and the polygon.
Point-in-polygon test against a fixed Calgary coordinate set (I use five points — downtown plus four quadrant centroids — so an alert clipping only the far northwest still registers).
Map the event to the internal vocabulary. Freezing rain and freezing drizzle map directly. For hail, ECCC issues severe thunderstorm watches and warnings whose text frequently mentions hail size; the mapper marks any severe-thunderstorm CAP as hail_risk and elevates confidence when the text matches hail-size patterns.
Frame the tire-relevant angle. For freezing rain: stopping distances, the limits of any tread compound on wet ice, and a pointer to our winter traction primer for the compound background. For hail: move the vehicle under cover if feasible, and afterwards inspect sidewalls and tread for bruising — with a note that impact damage is often repairable when caught early if it is in the tread face rather than the sidewall.

The cap_id field gives natural deduplication: CAP updates reference their predecessors, so an updated warning replaces rather than duplicates the advisory. More on the general mechanism below.

Deep cold and the TPMS false-alarm problem

Below about -25°C, two things happen that generate confused drivers. First, the pure physics above: a tire inflated to placard at 0°C is down roughly 4-5 PSI at -30°C, which is enough to cross the typical TPMS trigger threshold of 25% below placard on some vehicles. Second, direct-TPMS sensor batteries and radio electronics behave worse in extreme cold, so intermittent sensor-fault indications (as opposed to low-pressure warnings) become more common.

The deep_cold advisory therefore has an unusual goal: pre-empt panic. It fires when the forecast shows two consecutive lows at or below -25°C, and its content explains that a TPMS lamp on the first brutal morning most likely means "cold air is denser," what the difference between the low-pressure symbol and the sensor-fault symbol is, and that the correct response is to check with a gauge and add air — not to assume a puncture. For drivers who cannot comfortably do that at -30°C, the advisory mentions that our mobile service unit operates through cold snaps across the usual coverage zones. That is the sum total of self-reference this rule carries; the advisory is 90% physics explainer by word count, deliberately.

The -25°C arm / -20°C disarm pair is the hysteresis gap doing visible work. Calgary cold snaps frequently hover near the threshold; a symmetric threshold would toggle the advisory state daily.

Hysteresis: Designing Rules That Refuse to Flap

Flapping is the failure mode that kills advisory systems, so it gets its own machinery rather than per-rule improvisation. Every rule runs inside a shared state wrapper with four orthogonal anti-flap controls:

Split thresholds. Arm and disarm conditions differ by a deliberate gap (fire at -25°C, clear at -20°C; fire at ≥18°C swing, ignore swings under 12°C while active). The gap width is a tunable per rule, chosen from the backtest's flap counts.

Minimum hold time. Once armed, a rule cannot disarm for a configured period (12-72 hours depending on the rule) even if conditions momentarily recede. Forecast issuances wobble run to run; the hold time absorbs the wobble.

Persistence-to-fire. Conditions must hold across N consecutive evaluations before the first firing, as in the winter-window rule. This trades a few hours of latency for a large reduction in retracted advisories, and for every rule except the CAP-driven pair the trade is obviously right. CAP rules skip persistence — ECCC has already applied its own issuance discipline, and freezing-rain lead time is precious.

Cooldown after firing. After emitting, a rule sleeps for a per-rule window regardless of input. A chinook that oscillates for five days produces one advisory, not five.

The wrapper is small enough to show nearly whole:

@dataclass
class RuleState:
    armed_since: datetime | None = None
    last_fired: datetime | None = None
    latched: bool = False
    consecutive_hits: int = 0

    def observed(self, hit: bool) -> "RuleState":
        n = self.consecutive_hits + 1 if hit else 0
        armed = self.armed_since if hit else None
        if hit and armed is None:
            armed = utcnow()
        return replace(self, consecutive_hits=n, armed_since=armed)

    def held_for(self, hours: int) -> bool:
        return (self.armed_since is not None
                and utcnow() - self.armed_since >= timedelta(hours=hours))

    def in_cooldown(self, hours: int) -> bool:
        return (self.last_fired is not None
                and utcnow() - self.last_fired < timedelta(hours=hours))

State persists to a rule_state table keyed by rule_id, written transactionally with any advisory_event insert, so a process restart mid-evaluation cannot double-fire. That transactional pairing — state transition and event emission committing together or not at all — is the single most load-bearing line of design in the whole system.

Deduplication and Idempotency Keys

Hysteresis prevents rapid re-firing from the same rule instance; deduplication prevents the same logical event from producing multiple advisories through different paths. The two overlap but are not the same problem. Sources of logical duplicates I have actually observed:

The AMQP consumer and the fallback poller ingesting the same forecast issuance (handled at the snapshot layer by the unique constraint).
A CAP warning being updated four times during one freezing-rain event, each update a new file.
A restart replaying an evaluation against data that already produced an advisory.
Two rules describing one physical event — a sharp cold arrival can satisfy both chinook_swing and pressure_drop.

The mechanism is a deterministic dedup key per advisory, unique-constrained in the database:

def dedup_key(rule_id: str, window_start: date, window_end: date,
              site_id: str) -> str:
    basis = f"{rule_id}|{site_id}|{window_start.isoformat()}|{window_end.isoformat()}"
    return hashlib.sha256(basis.encode()).hexdigest()[:24]

The key deliberately excludes the firing timestamp and the evidence payload: two firings about the same window are the same advisory no matter when the pipeline noticed. For CAP rules, window_start/window_end come from the CAP onset/expiry, and the references chain in updated CAP messages collapses updates onto the original key with the evidence column appended rather than a new row inserted.

Cross-rule duplication gets a coarser tool: a suppression matrix. If pressure_drop wants to fire while a chinook_swing advisory for an overlapping window is already in delivered state, it writes its event with state='suppressed' — recorded, auditable, never sent. The matrix is a static config of (suppressor, suppressed, max window overlap) triples, currently three entries. I resisted making it clever; three static rows have covered every real collision in two seasons.

Backtesting Against Past Seasons

Threshold numbers without evaluation are vibes. The backtest harness replays historical data through the exact production rule code — same functions, same state wrapper — with a clock abstraction so utcnow() follows the replay.

Data. For observations, climate-daily gives clean ground truth back decades. Forecasts are the harder half: ECCC does not archive citypage forecasts in an easily queryable way, so I have been archiving every issuance myself since instrumenting the pipeline (which now covers two full winters), and for older seasons I approximate "what the forecast plausibly said" by applying a lag-and-noise model to observed dailies. Findings from the approximated seasons get a lower evidence tier and never justify a threshold change on their own.

Labels. Precision and recall require ground truth for "an advisory should have existed." I hand-labelled event windows per season from observed data plus ECCC's public seasonal summaries: the actual first sustained cold stretch, each ≥15°C 36-hour swing, each freezing-rain event, each hail event with confirmed Calgary impact, each ≤-25°C snap. Labelling five past seasons took an evening per season. It is boring work and it is the only reason the numbers below mean anything.

Metrics. Per rule, per season: true positives (fired within the labelled window or within its defined lead margin), false positives (fired with no matching label), false negatives (label with no firing), plus two operational counts — flaps (fire/clear/fire on one label) and lead time (hours between firing and label onset).

Design-example results from the replay of the two fully-archived winters, after the current thresholds settled:

Rule	Labels	TP	FP	FN	Precision	Recall	Median lead
`winter_window`	2	2	0	0	1.00	1.00	~5 days
`chinook_swing`	41	33	6	8	0.85	0.80	~14 h
`pressure_drop`	9	8	3	1	0.73	0.89	~30 h
`freezing_rain`	6	6	2	0	0.75	1.00	~4 h
`deep_cold`	4	4	1	0	0.80	1.00	~2 days

Reading that table honestly: chinook_swing misses one swing in five, almost always the ones the forecast itself underpredicted — an input ceiling, not a rule bug. pressure_drop runs the loosest precision, and I accept that because its advisory is the cheapest to receive (a gauge check costs a minute). The tuning principle that fell out of a season of fiddling: set each rule's threshold according to the cost asymmetry of its errors. Winter-window false negatives are the most expensive outcome in the whole catalogue, so that rule runs the most sensitive quorum the flap budget allows. Hail false positives are nearly free ("move the vehicle under cover" wastes five minutes), so hail_risk forwards every severe-thunderstorm CAP without second-guessing.

One meta-lesson: keep the backtest harness runnable in CI against a frozen fixture season. Twice, an innocuous refactor changed rule behaviour (a timezone slip; a quorum boundary going from < to <=), and the fixture replay caught both before production did.

Delivery: Rate Limiting, Quiet Hours, and the Audit Trail

An advisory in pending state enters the delivery layer, which owns four responsibilities and refuses to learn anything about meteorology.

Per-recipient rate limiting. Token bucket per recipient: capacity 3, refill one per 48 hours (design-example values). When the bucket is empty, lower-priority advisories drop — recorded with state='suppressed' and a suppression_reason — while the two highest-priority kinds (freezing_rain, hail_risk) may overdraw the bucket into a bounded deficit. The priority ordering is static config, reviewed seasonally.

Quiet hours with priority override. Nothing routine sends between 21:00 and 07:30 local; it queues for morning. Imminent-hazard kinds override, since a 22:10 hail cell does not wait for breakfast.

Channel fan-out. Email and SMS behind a common interface. Every message body is generated from the advisory evidence plus a template per (rule, audience) pair, and every message ends with the same two fixed elements: a plain-language "why you received this" line derived from the evidence JSON, and an unsubscribe path. Recipients opted in explicitly through the notification-preferences step of our online reservation flow; the pipeline maintains no other recipient source, and the seasonal-changeover reminder list from our changeover information page feeds the same consent store rather than a parallel one. Consent lives in one table with one meaning.

Audit logging. Every delivery attempt writes an append-only row:

CREATE TABLE delivery_audit (
    id              BIGSERIAL PRIMARY KEY,
    advisory_id     BIGINT NOT NULL REFERENCES advisory_event(id),
    recipient_hash  TEXT NOT NULL,      -- HMAC of recipient id, not the id
    channel         TEXT NOT NULL,
    attempted_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
    outcome         TEXT NOT NULL,      -- sent / bounced / rate_limited / quiet_hours
    provider_ref    TEXT,
    body_sha256     TEXT NOT NULL
);

Storing body_sha256 instead of the body keeps recipient content out of the audit table while still letting me prove exactly which template revision a given person received — the rendered bodies live in short-retention storage keyed by that hash. The audit table answered a real dispute last winter: a recipient was sure they had never been warned before a freezing-rain morning; the trail showed a bounced outcome from their expired address, which turned a trust complaint into an address update.

The whole delivery layer is intentionally dumb. Every interesting decision — should this exist, is it a duplicate, is it worth a human's attention — happens upstream where it can be backtested. The layer that touches humans only schedules, throttles, renders, and records.

Failure Modes Worth Designing For

A grab-bag of production lessons that did not fit elsewhere, each earned the annoying way:

The AMQP connection dies silently. Heartbeats help but do not catch everything. The real safeguard is an end-to-end freshness check: if the newest forecast_snapshot.issued_at is older than 8 hours, page me — citypage forecasts refresh far more often than that, so staleness means ingestion is broken regardless of which component lied.
ECCC file formats drift. Rarely and usually announced, but the parser treats any unmapped structure as a soft failure that quarantines the file and alerts, rather than a crash or — worse — a silent partial parse.
Station data has holes. climate-daily rows can arrive late or flagged. Every aggregate over observations carries a minimum-coverage requirement (≥5 of 7 trailing days present) and rules degrade to forecast-only evidence, noted in the evidence JSON, when coverage fails.
Clock discipline. The replay clock abstraction leaked into production once, freezing a rule's idea of "now" at process start. Rule code now receives time as an argument; nothing below the entrypoint imports a clock.
Threshold drift review. Once a season, the labelled-event set gets extended and every threshold re-justified against the updated table. Thresholds that survive because nobody looked are just superstition with a config file. The general tire-knowledge material we maintain gets the same seasonal review pass, for the same reason.

What I Would Tell You to Build First

If you are standing up something similar — for tires, HVAC, roofing, agriculture, anything where weather drives maintenance urgency — the ordering that would have saved me a month:

Archive forecasts from day one, even before you have rules. The observation history is free from GeoMet forever; the forecast history only exists if you save it, and every serious evaluation question needs both.
Build the normalized schema and the labelling workflow before the rules. Rules are an afternoon each once the data is typed and the ground truth exists; they are endless if every rule is also a parser and its own judge.
Make hysteresis shared infrastructure, not per-rule cleverness. The four controls above cover every flapping pattern I have met.
Wire the audit trail before the first real recipient. Retrofitting provenance is miserable; recording it from the start is one table.

The pipeline is a few thousand lines of Python, one PostgreSQL database, and a handful of static config tables. Nothing in it is architecturally exotic. Its value comes from the specificity of the domain rules — the 7°C compound crossover, the 1 PSI per 5-6°C derivation at Calgary's altitude, the arm/disarm gaps sized to chinook behaviour — and from the discipline of measuring the rules against seasons that actually happened. Weather data is abundant and free; restraint is the part you have to build yourself.

KMJ Tire is an independent Calgary tire and oil-change business. Everything above describes internal tooling; thresholds and results are design examples from our configuration and replays, not universal constants. The public-facing side of the winter-timing rule lives on our seasonal changeover page.

Modeling Seasonal Tire-Changeover Demand: Queueing Math and Slot-Scheduler Design for a Calgary Tire Shop

KMJ Tire Calgary — Sat, 08 Aug 2026 16:10:44 +0000

Modeling Seasonal Tire-Changeover Demand: Queueing Math and Slot-Scheduler Design for a Calgary Tire Shop

Twice a year, a tire counter in Calgary experiences something that most service businesses never see: demand that is gated not by a date, but by a weather forecast. When Environment Canada's seven-day outlook shows the first hard freeze of the fall, request volume for seasonal tire changeovers can triple within forty-eight hours. When the first real snowfall actually lands, it triples again. The spring side is gentler but still lumpy: a string of warm days pulls everyone in at once to get winter rubber off before it wears down on hot pavement.

This article is a design study. It walks through how you would model that demand mathematically, sanity-check capacity with queueing theory, replace the closed-form math with a discrete-event simulation when the assumptions break, and then design the slot-scheduling data model that turns the analysis into software. The operational grounding is real — KMJ Tire is a Calgary operation that does tire work and oil changes, and the seasonal spike described here is the actual shape of its year — but the system described is a design exercise, not a description of live production infrastructure. All numeric figures in the worked examples are illustrative and labelled as such.

One scoping note before the math: the service catalog here is deliberately narrow. Tire changeovers, mounting and balancing, flat repairs, and oil changes. No alignments, no brakes, no diagnostics. That narrowness is a modeling gift. A general repair garage has service times ranging from twenty minutes to three days, which makes capacity planning a nightmare. A tire-and-oil operation has maybe five job types, each with a tight, estimable duration distribution. If you ever get to choose a domain for your first scheduling system, choose one like this.

Why Changeover Demand Is Not a Calendar Event

A naive scheduler assumes demand follows the calendar: busy in late October, busy in late April, quiet otherwise. Calgary breaks that assumption in both directions.

First, the trigger is meteorological. The fall rush does not start on October 15th; it starts when the forecast says overnight lows will hold below zero, and it goes vertical the morning after the first snowfall that sticks. In some years that is October 2nd. In others it is November 9th. A model keyed to calendar dates will be five weeks wrong in either direction, which at peak volume means either an empty schedule grid or a two-week backlog.

Second, chinooks generate false starts. A chinook arch can take the city from minus fifteen to plus twelve in a day. Early-season cold snaps followed by two warm weeks produce a demand spike, then a dead zone, then a second spike when winter arrives for real. Drivers who held out through the first snap because "it'll melt" — and it did — show up in the second wave with more urgency. Any intensity model needs to handle multiple partial triggers per season, not one clean step function.

Third, the two seasons are asymmetric, and this matters more than most people expect. The fall changeover is deadline-driven: there is a morning when the roads are white and every all-season tire in the city becomes a liability at once. The spring changeover has no deadline. Winter tires on dry warm pavement wear faster and cost the owner money slowly, but nobody slides into an intersection because they left them on until June. Fall demand is therefore a sharp impulse with a heavy leading edge; spring demand is a wide, flat-topped hump spread over five or six weeks. A model trained on one and applied to the other will fail quietly, which is worse than failing loudly.

Fourth, product mix shifts the load. Customers running all-weather tires opt out of the changeover cycle entirely — that is much of their appeal — while dedicated winter tire owners are locked into two visits a year. As the all-weather share of the local fleet grows, the seasonal amplitude damps. Your demand model has a slow secular trend underneath the annual cycle, and if you fit only on last year you will miss it.

Demand as a Non-Homogeneous Poisson Process

The standard formalism for arrival streams whose rate varies over time is the non-homogeneous Poisson process (NHPP). Requests arrive independently, but the arrival intensity λ(t) is a function of time rather than a constant. For our problem, λ(t) is a function of time and weather state:

λ(t) = λ_base(t) · m_weather(F_t) · m_backlog(B_t)

where:

λ_base(t) is the baseline seasonal-and-weekly pattern: day-of-week effects (Saturdays run hot, Tuesdays run cold), plus a smooth annual curve.
m_weather(F_t) is a multiplier driven by the forecast feature vector F_t — things like minimum forecast temperature over the next 7 days, probability of accumulating snowfall, and days since the first freeze of the season.
m_backlog(B_t) captures reflexive demand: when the wait to the next open slot stretches past a few days, some fraction of would-be requesters defer or go elsewhere, which suppresses observed arrivals. Ignoring this term makes you overestimate peak intensity from historical data, because the historical peaks were already demand-suppressed.

The weather multiplier is where the Calgary-specific behaviour lives. A reasonable functional form is a saturating response to a "trigger score":

import math
from dataclasses import dataclass

@dataclass
class ForecastFeatures:
    min_temp_7d: float        # coldest forecast overnight low, next 7 days (Celsius)
    snow_prob_72h: float      # probability of accumulating snow within 72h, 0..1
    days_since_first_freeze: float | None  # None if it has not happened yet
    season: str               # "fall" or "spring"

def trigger_score(f: ForecastFeatures) -> float:
    """Scalar in [0, ~3] summarizing how strongly weather is pushing demand.

    Coefficients below are illustrative placeholders, not fitted values.
    """
    s = 0.0
    if f.season == "fall":
        # Cold forecast pulls demand forward even before snow falls.
        s += max(0.0, (2.0 - f.min_temp_7d) / 6.0)      # ramps as lows drop below +2C
        s += 1.6 * f.snow_prob_72h                       # imminent snow dominates
        if f.days_since_first_freeze is not None:
            # Urgency decays ~2 weeks after the first freeze as the herd clears.
            s += 0.8 * math.exp(-f.days_since_first_freeze / 9.0)
    else:  # spring
        # Sustained warmth, not a single warm day, drives spring swaps.
        s += max(0.0, (f.min_temp_7d - 4.0) / 5.0)
    return s

def weather_multiplier(f: ForecastFeatures, cap: float = 4.5) -> float:
    """Map trigger score to a demand multiplier with a saturating ceiling."""
    s = trigger_score(f)
    return 1.0 + (cap - 1.0) * (1.0 - math.exp(-1.1 * s))

Two design choices deserve defense. The exponential saturation reflects a hard truth: demand cannot multiply forever, because the population of vehicles needing a swap is finite. Every changeover performed depletes the pool. A proper treatment would model the susceptible population explicitly — an SIR-flavoured depletion model, where "infection" is the first snowfall — but the saturating multiplier gets you most of the way with far less machinery.

The decay term on days_since_first_freeze encodes the herd-clearing effect. Ten days after the first snow, most of the panicked demand has either been served or has given up for the moment. Historical intensity plots (in this shop's records and, anecdotally, at every tire counter in the city) show a spike with roughly exponential relaxation, punctuated by secondary spikes on each subsequent snowfall.

To generate synthetic arrivals from an NHPP for simulation, thinning (Lewis and Shedler's method) is the standard tool: simulate a homogeneous process at the maximum rate, then keep each arrival with probability λ(t)/λ_max.

import random

def nhpp_arrivals(lam, lam_max, t_end, rng=random.Random(42)):
    """Thinning: yield arrival times in [0, t_end) for intensity function lam(t)."""
    t = 0.0
    while True:
        t += rng.expovariate(lam_max)
        if t >= t_end:
            return
        if rng.random() < lam(t) / lam_max:
            yield t

Fitting λ(t) from historical data is a Poisson regression: count requests per day, regress on the weather features and day-of-week dummies with a log link. Even a plain GLM does respectably here because the feature set is small and physically motivated. Resist the urge to reach for a gradient-boosted model with forty features; you have at most a dozen seasonal transitions in your entire dataset, and flexibility without data is just a curve-fitting liability.

Service Times: Two Distributions, Not One

The second half of any queueing model is the service process, and here the job-type split is everything. A changeover comes in two fundamentally different flavours:

Swap on rims. The customer owns two full sets of mounted wheels. The job is: lift, off, on, torque, set pressures, verify TPMS. Fast, predictable, low variance.
Mount and balance. One set of rims, two sets of rubber. Each tire comes off its rim and the seasonal tire goes on, followed by balancing on the spinner. Slower, and with a longer tail: corroded bead seats, stubborn TPMS relearn procedures, and the occasional stripped-thread surprise on the lug hardware all live in that tail.

Oil changes ride along as a third job type — shorter still, and usefully counter-cyclical, since they can backfill quiet slots in the off-season without competing hard for peak-season bay time.

Illustrative distribution parameters, stated as such (these are plausible for a shop of this type, not measured production values):

Job type	Distribution	Median	p90	Notes
Swap on rims	Lognormal(μ=ln 32, σ=0.22)	32 min	~42 min	Includes vehicle in/out and torque check
Mount + balance (4 tires)	Lognormal(μ=ln 62, σ=0.35)	62 min	~97 min	Tail driven by bead corrosion, TPMS relearn
Oil change	Lognormal(μ=ln 24, σ=0.18)	24 min	~30 min	Filler work between peak jobs

Why lognormal rather than exponential? Because the exponential assumption — memoryless service, mode at zero — is flatly wrong for physical work. Nobody completes a four-wheel swap in ninety seconds, and the empirical histograms of hands-on automotive tasks are right-skewed with a hump well away from zero. Lognormal (or gamma) fits that shape. The distinction matters practically: the M/M/c formulas assume exponential service, and using them with lognormal reality means your closed-form answers are approximations from the start. They are still worth computing — as a sanity check, not as a forecast.

Estimating these distributions is the easiest data problem in the whole system, provided your point-of-sale or work-order timestamps are trustworthy. Take start/finish pairs per job type, filter out the obviously-broken records (the four-second mount/balance means someone closed the ticket late), and fit by maximum likelihood on the log of duration. Fifty observations per job type gives you a serviceable estimate; a full season gives you a good one. The one trap: peak-season service times are longer than off-season ones for the same job type, because techs are interrupted more, staging space is congested, and the vehicles arriving are disproportionately the annoying ones. Fit peak and off-peak separately or include a load covariate.

An M/M/c Sanity Check, and Where It Lies to You

With arrival and service rates in hand, the classical move is Erlang-C: model the operation as an M/M/c queue with c parallel servers (bays with a tech), Poisson arrivals at rate λ, exponential service at rate μ per server, and compute the probability an arriving job waits, plus the expected wait.

from math import factorial

def erlang_c(c: int, offered_load: float) -> float:
    """P(wait > 0) for M/M/c with offered load a = lambda/mu erlangs."""
    a = offered_load
    rho = a / c
    if rho >= 1.0:
        return 1.0  # unstable: queue grows without bound
    b = (a ** c) / factorial(c)
    denom = sum((a ** k) / factorial(k) for k in range(c)) + b / (1 - rho)
    p_wait = (b / (1 - rho)) / denom
    return p_wait

def mean_wait_hours(c: int, lam: float, mu: float) -> float:
    a = lam / mu
    return erlang_c(c, a) / (c * mu - lam)

Here is the part practitioners underestimate. Utilization of 85–90% sounds healthy — it is what a spreadsheet-driven manager will target — but in a stochastic system it is already deep into the pain zone, because waits blow up hyperbolically as ρ approaches 1. We will put concrete numbers on that in a moment.

Where the model lies, and why you should not stop here:

Non-stationarity. M/M/c describes steady state. A changeover surge is a transient — the system never settles. Steady-state formulas applied to a two-week impulse answer a question nobody asked.
Wrong service distribution. Exponential service understates the probability of medium-length jobs and overstates very short ones. M/M/c wait estimates are optimistic when reality is lognormal with our σ values (the coefficient of variation is below 1, which actually helps — but the tail events hurt in ways the mean does not capture).
Heterogeneous jobs and resources. A bay with a tire machine and spinner can do everything; a flat stall can only do swaps and oil. That is not "c identical servers."
Scheduled arrivals are not Poisson. The entire point of a reservation system is to destroy the Poisson property — to replace random arrivals with a controlled admission process. M/M/c models the walk-in-only world you are trying to escape.

So use Erlang-C the way you use a back-of-envelope structural calculation: to determine whether the design is off by a factor of three, before you spend a week building the simulation that answers the real question.

Worked Example: Four Bays Against a Freeze Warning

Everything in this section is an illustrative calculation with invented-but-plausible inputs, labelled as such. It exists to show the method, not to publish operating data.

Setup. Four equivalent bays, nine working hours per day. Job mix during the fall surge: 60% swap-on-rims, 40% mount-and-balance. Using the medians above as means (close enough for this level), the blended mean service time is:

E[S] = 0.6 × 32 min + 0.4 × 62 min = 19.2 + 24.8 = 44 min ≈ 0.733 h
μ ≈ 1.36 jobs per bay-hour

Scenario A — a moderately busy shoulder day. Suppose requests arrive at λ = 4.5 per hour. Offered load a = λ/μ = 3.31 erlangs across c = 4 bays, so utilization ρ = 0.83. Plugging into Erlang-C:

P(wait) ≈ 0.66
Wq = P(wait) / (cμ − λ) ≈ 0.66 / (5.44 − 4.50) ≈ 0.70 h ≈ 42 minutes

Read that again: at 83% utilization — a number most planning spreadsheets would color green — two-thirds of arriving vehicles wait, and the average wait is roughly three-quarters of a service time. Push λ to 5.1 per hour (ρ = 0.94) and mean wait quadruples to nearly three hours. That hyperbolic blowup near saturation is the single most important intuition queueing theory offers, and it is exactly why "we'll just work faster during the rush" is not a plan.

Scenario B — the morning after the first snowfall. Historical pattern (again, stylized): request volume equivalent to 110 changeovers in one day. Daily throughput ceiling with four bays is:

4 bays × 9 h × 1.36 jobs/bay-hour ≈ 49 jobs/day

Demand is 2.2× capacity. No queueing formula rescues this; the system is simply oversubscribed, and the interesting quantity stops being "wait in the lobby" and becomes "days until the next open slot." The 61 unserved requests roll forward, meet the next day's fresh arrivals, and the backlog integrates upward until either intensity decays (the herd-clearing effect) or capacity rises (surge policy — extended hours, overflow days, or diverting swap-on-rims jobs to a mobile service unit that handles them in customer driveways and office parking lots).

This is the pivotal reframing for the whole design: during the surge, the queue does not live in the waiting room; it lives in the schedule. The engineering objective is not minimizing lobby wait — it is shaping the multi-day backlog: keeping p90 time-to-next-open-slot bounded, protecting emergency capacity, and making sure the reservation grid, not a phone-line free-for-all, absorbs the shock.

Discrete-Event Simulation When the Formulas Run Out

Once you accept non-stationary arrivals, lognormal services, heterogeneous bays, reservations, no-shows, and walk-ins, closed forms are gone. A discrete-event simulation (DES) handles all of it and stays small enough to read in one sitting. The core is a priority queue of timestamped events:

import heapq, random

class ChangeoverSim:
    """Minimal DES: reserved arrivals + walk-ins competing for bays.

    All parameters illustrative. Times in hours from day start.
    """
    def __init__(self, n_bays=4, day_len=9.0, seed=7):
        self.rng = random.Random(seed)
        self.n_bays = n_bays
        self.day_len = day_len
        self.events = []            # (time, seq, kind, payload)
        self.free_bays = n_bays
        self.queue = []             # waiting jobs (on-site)
        self.stats = {"served": 0, "waits": [], "balked": 0}
        self._seq = 0

    def push(self, t, kind, payload=None):
        self._seq += 1
        heapq.heappush(self.events, (t, self._seq, kind, payload))

    def service_time(self, job_type):
        med, sigma = {"swap": (32/60, 0.22),
                      "mount": (62/60, 0.35),
                      "oil":  (24/60, 0.18)}[job_type]
        return self.rng.lognormvariate(0, sigma) * med

    def arrive(self, t, job):
        if self.free_bays > 0:
            self.start(t, job)
        elif len(self.queue) >= 6 and job["source"] == "walkin":
            self.stats["balked"] += 1        # walk-in sees a full lobby, leaves
        else:
            job["t_arr"] = t
            self.queue.append(job)

    def start(self, t, job):
        self.free_bays -= 1
        self.stats["waits"].append(t - job.get("t_arr", t))
        self.push(t + self.service_time(job["type"]), "done")

    def run(self):
        while self.events:
            t, _, kind, payload = heapq.heappop(self.events)
            if kind == "arrive":
                self.arrive(t, payload)
            elif kind == "done":
                self.free_bays += 1
                self.stats["served"] += 1
                if self.queue:
                    self.start(t, self.queue.pop(0))
        return self.stats

Feed it two arrival streams: the reserved stream (slot times, each realized with probability 1 − p_noshow, plus a lateness jitter of a few minutes either way) and the walk-in stream (NHPP via the thinning generator above, with intensity spiking on snowfall mornings). Run a few hundred replications per scenario and look at distributions, not means — the p90 lobby wait and the count of jobs still unfinished at closing time are the numbers that decide staffing arguments.

What the simulation buys you over the algebra, concretely: you can ask policy questions. What happens to overtime hours if we admit walk-ins only into dedicated walk-in slots? How much does a 15-minute buffer after every third mount-and-balance reduce end-of-day overruns? Is one extended-hours evening worth more than a Sunday overflow day? Each of those is a one-line configuration change in the sim and an unanswerable question in Erlang-land.

Two implementation notes from the trenches. Seed your random generators explicitly and log the seed with every run, or you will chase phantom regressions between "identical" scenarios. And validate the sim against the M/M/c case first: set exponential services, constant λ, homogeneous bays, and confirm the simulated waits match Erlang-C within confidence bounds. A DES that cannot reproduce the textbook case has a bug you will otherwise discover much later, in an argument, with money on the table.

Designing the Slot Data Model

Now the software half. The reservation grid is the mechanism that converts stochastic chaos into scheduled work, and its data model determines what policies you can even express. The entities that have earned their place:

Job types. Each with a planning duration (not the mean — typically the p75 of the fitted distribution, so that half your slots do not run over), a required-equipment flag set, and a seasonal-relevance tag.
Resources. Bays and techs, modelled separately. A bay without a tire-machine-certified tech is storage; a tech without a bay is idle. Capacity at any instant is the min of qualified-tech count and equipped-bay count for a given job type. Small operations can collapse this to "staffed bay" as a single resource and split it later; the schema below leaves room.
Slot templates. The pattern that generates concrete slots: "weekdays, bay 1–3, 45-minute grid from 08:00 to 17:00; Saturday adds bay 4." Templates carry an effective-date range, which is exactly the hook that surge policy will use.
Slots. Materialized rows, generated from templates out to a rolling horizon (three weeks is a comfortable default). Materializing — rather than computing availability on the fly — makes the availability query trivial, makes capacity auditable ("show me every slot we offered in week 44"), and gives overbooking a concrete object to attach to.
Reservations. A customer request pinned to a slot, carrying job type, vehicle info, status lifecycle (held → confirmed → arrived → in_service → completed | no_show | cancelled), and the channel it came through (the online reservation page, phone, or counter).
Walk-in log. Every walk-in, served or not. The unserved ones are your only direct evidence of demand exceeding supply — treasure them.

The buffer policy deserves its own paragraph because it is the most commonly botched piece. If planning durations are honest p75s, roughly one job in four still overruns its slot. Without buffers, overruns cascade: by 3 p.m. every bay is running forty minutes late and the lobby is hostile. The fix is structural slack — either a buffer minute-count appended per slot, or (cleaner) sacrificial catch-up slots: one slot per bay per half-day that is never offered for sale and exists to absorb accumulated drift. Which is better depends on your overrun distribution; the sim answers it in an afternoon.

Overbooking is the same idea mirrored. With a no-show probability of, illustratively, 8–12% on freeze-week days (people's plans change fast when a chinook rolls in and the snow melts), selling exactly one reservation per slot wastes a tenth of your scarcest capacity. Deliberately over-admitting into designated overbookable slots — at a ratio derived from the no-show rate, airline style but far lower stakes — recovers it. Critically, both buffers and overbooking ratios must live in data, not code, because you will tune them seasonally.

Schema Sketches

PostgreSQL flavour. Abbreviated to the load-bearing columns; production versions would add tenancy, audit, and soft-delete concerns.

CREATE TABLE job_types (
    id            SMALLSERIAL PRIMARY KEY,
    code          TEXT UNIQUE NOT NULL,          -- 'swap_rims' | 'mount_balance' | 'oil_change'
    plan_minutes  SMALLINT NOT NULL,             -- p75 of fitted duration, reviewed seasonally
    needs_mounter BOOLEAN NOT NULL DEFAULT false,
    seasonal      BOOLEAN NOT NULL DEFAULT false
);

CREATE TABLE resources (
    id         SMALLSERIAL PRIMARY KEY,
    kind       TEXT NOT NULL CHECK (kind IN ('bay','tech')),
    label      TEXT NOT NULL,
    capability JSONB NOT NULL DEFAULT '{}'::jsonb   -- {"mounter": true, "hoist": "10k"}
);

CREATE TABLE slot_templates (
    id            SERIAL PRIMARY KEY,
    name          TEXT NOT NULL,                  -- 'weekday_standard', 'surge_evening'
    dow_mask      INT NOT NULL,                   -- bitmask Mon..Sun
    start_local   TIME NOT NULL,
    end_local     TIME NOT NULL,
    grid_minutes  SMALLINT NOT NULL,
    bay_id        INT NOT NULL REFERENCES resources(id),
    effective     DATERANGE NOT NULL,             -- surge policy activates/retires templates
    overbook_pct  NUMERIC(4,1) NOT NULL DEFAULT 0,
    buffer_min    SMALLINT NOT NULL DEFAULT 0
);

CREATE TABLE slots (
    id          BIGSERIAL PRIMARY KEY,
    template_id INT REFERENCES slot_templates(id),
    bay_id      INT NOT NULL REFERENCES resources(id),
    span        TSTZRANGE NOT NULL,
    sellable    BOOLEAN NOT NULL DEFAULT true,    -- false for catch-up/buffer slots
    max_admits  SMALLINT NOT NULL DEFAULT 1,      -- >1 only where overbooking applies
    EXCLUDE USING gist (bay_id WITH =, span WITH &&)  -- no overlapping slots per bay
);

CREATE TABLE reservations (
    id           BIGSERIAL PRIMARY KEY,
    slot_id      BIGINT NOT NULL REFERENCES slots(id),
    job_type_id  SMALLINT NOT NULL REFERENCES job_types(id),
    vehicle_ref  TEXT NOT NULL,
    channel      TEXT NOT NULL CHECK (channel IN ('web','phone','counter')),
    status       TEXT NOT NULL DEFAULT 'held'
                 CHECK (status IN ('held','confirmed','arrived','in_service',
                                   'completed','no_show','cancelled')),
    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    status_at    TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE walkin_log (
    id          BIGSERIAL PRIMARY KEY,
    seen_at     TIMESTAMPTZ NOT NULL,
    job_type_id SMALLINT REFERENCES job_types(id),
    outcome     TEXT NOT NULL CHECK (outcome IN ('served','deferred_to_slot','left')),
    est_wait_quoted_min SMALLINT
);

A few deliberate choices worth defending:

The EXCLUDE USING gist constraint on slots is PostgreSQL doing your concurrency control for you: two overlapping spans on the same bay cannot both commit, no matter how badly your slot-generation job misbehaves. Range types plus exclusion constraints are the single most underused feature in scheduling systems built on Postgres.

Admission control belongs in one place. The invariant "count of active reservations on a slot ≤ max_admits" is enforced in a single transactional path — a serializable transaction or an advisory lock keyed on slot_id — never sprinkled across application layers. Every double-admission bug in every scheduling system traces back to someone checking availability in one query and inserting in another without isolation.

Status history matters more than current status. The sketch shows only status_at; a production build appends every transition to an event table instead. The reason is the analytics, not the operations: no-show modelling requires knowing when the no-show became apparent, and demand modelling requires created_at (when did they ask?) separated from slot time (when did we serve them?). Lead-time distribution — the gap between the two — is itself a surge signal: it collapses toward zero right before the crunch, as urgency rises.

No-Shows and Walk-Ins Are Inputs, Not Noise

It is tempting to treat no-shows and walk-ins as operational irritants to be minimized. In the model they are first-class stochastic inputs, and each carries information.

No-shows during freeze week have a distinctive cause: weather whiplash. A driver reserves in a panic on Tuesday's forecast; Thursday a chinook wipes the snow out; Friday's slot quietly goes unused. This means the no-show probability is itself weather-conditional — rising when the trigger that generated the reservation reverses. A two-variable logistic model (lead time at creation, temperature delta between creation day and slot day) captures most of it. The practical payoff: on forecast-reversal days you can raise the overbooking ratio on overbookable slots with quantified confidence rather than a shrug, and release predicted-dead capacity back to the waitlist a day early.

Walk-ins are the inverse problem: unscheduled supply-seeking. The morning after the first snowfall, some fraction of the city skips the reservation system entirely and drives over. A slot grid with zero walk-in allowance turns those visits into pure friction — every one interrupts the counter, and most leave unserved. A grid that holds back a small ration of same-day capacity (two or three sellable-but-unreleased slots per day, released each morning) converts walk-in pressure into scheduled work a few hours later. The walkin_log table exists to size that ration: outcome = 'left' rows are censored demand, the people the schedule failed. During surge analysis they get added back into the intensity estimate, because the reservation stream alone systematically undercounts true demand at exactly the moments you most need to know it. The same censoring logic applies to commercial and fleet work, where a fleet coordinator who cannot get five vans in this week may quietly move all five elsewhere — high-value demand that vanishes without a trace unless logged.

Surge Policy Is Configuration, Not Code

The worst version of surge handling is a developer editing constants the night after the first snowfall. The whole point of the template/effective-range design is that surge response is a data change: activate prebuilt templates, adjust ratios, done.

A surge configuration might look like this (structure illustrative):

surge_tiers:
  - name: watch          # freeze forecast inside 7 days, no snow yet
    activate_templates: []
    overbook_pct: 8
    walkin_holdback_per_day: 2
    demand_multiplier_floor: 1.4
  - name: freeze_rush    # first freeze confirmed or snowfall prob > 60% in 72h
    activate_templates: [surge_evening]       # weekday 17:00-20:00 grid
    overbook_pct: 12
    walkin_holdback_per_day: 4
    max_mount_balance_share: 0.45             # protect throughput with faster jobs
  - name: snowfall_peak  # accumulating snow on the ground
    activate_templates: [surge_evening, overflow_sunday]
    overbook_pct: 12
    walkin_holdback_per_day: 6
    defer_nonseasonal_jobs: true              # oil changes offered next-week slots

Note the max_mount_balance_share knob. During the crunch, throughput is king, and swap-on-rims jobs move nearly twice as many vehicles per bay-hour as mount-and-balance jobs. Biasing the sellable mix toward swaps — while routing mount-and-balance requests a few days out — raises vehicles-served-per-day exactly when that metric matters most. That is a policy decision with real trade-offs (mount-and-balance customers wait longer), which is precisely why it should sit in reviewable configuration with an audit trail, not in an if statement someone forgets.

Tier transitions should be proposed automatically (the weather-feature pipeline below emits a recommended tier each morning) but applied by a human. Full automation of surge policy is how you end up with an evening shift activated by a botched forecast parse. The human is cheap; the false activation is not.

Geography enters here too. Surge templates for the mobile unit look different from bay templates — drive time between stops is the dominant cost, so its "slots" are route-clustered by quadrant rather than gridded by the hour, and the service-area definition effectively becomes part of capacity policy: tightening the served radius during peak week is another lever that trades coverage for throughput.

Weather Features Feeding the Demand Multiplier

The forecasting layer can stay almost embarrassingly simple. Inputs, refreshed each morning:

7-day forecast: daily highs, lows, snowfall probability and expected accumulation.
Season state: days since first freeze (fall) or days of sustained warmth (spring).
Trailing demand: requests per day over the last 14 days, which anchors λ_base.

From these, compute tomorrow-through-day-7 expected intensity:

def daily_intensity_forecast(base_by_dow, features_by_day):
    """Return list of (date, expected_requests) for the next 7 days.

    base_by_dow: fitted baseline requests per day-of-week (off-season anchor)
    features_by_day: list of (date, ForecastFeatures)
    """
    out = []
    for date, feats in features_by_day:
        lam = base_by_dow[date.weekday()] * weather_multiplier(feats)
        out.append((date, lam))
    return out

Then compare forecast intensity against materialized sellable capacity per day, and emit three numbers to whoever runs the counter: expected requests, open slots, and projected p90 days-to-next-slot if the forecast verifies. That last number is the early-warning siren. When it crosses a threshold (say, four days — illustrative), the system recommends the next surge tier, and the humans decide.

A note on data sourcing discipline: forecast features must be snapshotted at prediction time. If you later backfill weather data with what actually happened, your model evaluation silently upgrades from "what did the forecast know" to "what did the atmosphere do," and every skill metric you compute becomes a lie. Store the forecast as-of each morning, forever. Disk is cheap; unreproducible evaluations are not.

The educational content angle deserves one sentence: demand shaping is also possible upstream. Content that helps drivers decide earlier — like the explainer material in the Be Tire Smart pages or a plain-language piece on reading sidewall markings — flattens the spike slightly by converting day-after-snowfall panic into week-before-freeze planning. The effect is modest, but it is the only lever that adds capacity by moving demand instead of moving staff.

Metrics That Decide Arguments

Instrument the system around a small set of numbers, each answering a specific operational question:

Metric	Definition	Question it answers
p90 time-to-next-slot	90th percentile, per job type, of (earliest open sellable slot − now)	Are we absorbing demand or falling behind?
Bay utilization (busy)	In-service minutes ÷ staffed-bay minutes	Are we paying for idle capacity?
Bay utilization (committed)	(In-service + reserved-future) ÷ sellable	How full is the forward grid?
Overrun rate	Share of jobs exceeding plan_minutes	Are planning durations still honest?
No-show rate (weather-split)	No-shows ÷ confirmed, segmented by forecast-reversal flag	Is the overbooking ratio calibrated?
Walk-in loss	`walkin_log.outcome = 'left'` per day	How much demand did we visibly turn away?
Reservation lead time	Median (slot time − created_at)	Is the surge approaching? (It collapses first.)
End-of-day drift	Actual last-job finish − scheduled last-slot end	Are buffers sized right?

Two of these earn special emphasis. The lead-time collapse is the best leading indicator in the whole system: days before request volume spikes, the gap between "when people ask" and "when they want service" shrinks from a week to a day. It is demand urgency made measurable, and it typically fires before the weather multiplier does, because drivers watch forecasts too. And walk-in loss is the only metric on the list measuring what did not happen — the abandonment that every purely reservation-based dataset is blind to. A dashboard without it will tell you the surge went fine when in fact you shed a triple-digit number of visits to competitors across the city; for a single-location independent among Calgary's local tire operations, those are exactly the first-time customers whose second visit you never get.

Resist vanity metrics. Total vehicles served per week is seasonal noise wearing a KPI costume; it mostly measures the weather. Every number on the dashboard should change someone's decision — slot ratios, staffing, surge tier — or it is decoration.

Pitfalls: The Ways This Model Fails

Overfitting to last season. One year of Calgary data contains exactly one fall trigger and one spring thaw, each with its own idiosyncratic timing. A model fit tightly to last October will confidently predict this October wrong. The defense is structural: keep the weather-response function low-dimensional and physically interpretable (cold → more demand, saturation, decay), pool multiple years even if older data is scrappier, and treat every fitted coefficient with the suspicion appropriate to n = 3 seasonal transitions. When forced to choose between a clever model and a dumb robust one, in this domain, choose dumb.

Ignoring the fall/spring asymmetry. Already discussed, but it recurs at the policy layer too: fall surge tiers built around throughput protection make no sense in spring, when the problem is a long moderate hump, not an impulse. Spring's failure mode is the opposite — weeks of slightly-elevated demand that never technically triggers a surge tier but accumulates a quiet backlog. Separate tier definitions per season; do not parameterize one set and hope.

Trusting duration data collected under load. Peak-week service times are contaminated by the peak itself. If you refit plan_minutes from surge-week data, durations inflate, slots lengthen, sellable capacity drops next season, and you have institutionalized your worst week. Fit from shoulder-season data; validate against peak.

Chinook double-triggering. A naive trigger fires on the first freeze, decays, then fires again on the next cold snap at full strength — but the second wave draws from a partially depleted population. Without a depletion term (or at minimum a season-to-date served-count discount), you will over-staff the second spike. The population of not-yet-swapped vehicles is finite and every completed changeover shrinks it; by late November the pool is mostly drained regardless of what the thermometer does. Track cumulative seasonal completions as an explicit state variable — it also quietly improves the fleet-side planning, since fleet accounts complete their changeovers in scheduled blocks that deplete pooled demand in visible chunks.

Letting the abstraction leak upward. The final trap is organizational. Queueing math and simulations produce distributions; managers want single numbers. The moment someone summarizes "p90 next-slot of 3.1 days under the 60%-snowfall scenario" as "we're fine," the modelling effort becomes theatre. Report ranges. Show the bad percentile. The entire value of the stochastic treatment is refusing to pretend the future is a point estimate.

Closing Notes From the Bay Floor

Strip away the notation and the design reduces to four moves. Model arrivals as weather-driven and non-stationary, because in this city they are. Use closed-form queueing only to bound the problem, then simulate, because every real complication — lognormal tails, mixed job types, no-shows, walk-ins — breaks the textbook assumptions in ways that matter. Put every policy knob in configuration with an effective-date range, because surge response has to move at forecast speed, not release-cycle speed. And instrument the censored demand — the visits that never happened — because that is where oversubscribed systems hide their failures.

None of this requires heavy infrastructure. The whole stack sketched here is a Postgres schema, a few hundred lines of Python, a YAML file, and a morning cron job reading a public forecast feed. What it requires instead is respect for the problem's actual structure: a finite, weather-triggered, twice-yearly stampede through a small number of bays, asymmetric between seasons, observed only partially. Get the structure right and modest tools are plenty. Get it wrong and no amount of machinery will save the second week of November — and anyone who has watched the first-snowfall morning from behind a tire counter, phone ringing over the torque wrenches, knows exactly which week that is.

Modelling a Mobile Service Area: Why Postal Codes Lie and Drive-Time Polygons Do Not

KMJ Tire Calgary — Fri, 07 Aug 2026 16:13:47 +0000

Modelling a Mobile Service Area: Why Postal Codes Lie and Drive-Time Polygons Do Not

Every business that sends a vehicle to a customer eventually writes the same function. It takes an address and returns a boolean. Somebody names it is_serviceable, somebody else names it in_zone, and the first implementation is almost always a Python set of postal code prefixes copied out of a spreadsheet that a dispatcher maintained by hand.

I write software for KMJ Tire, a small Calgary operation whose entire service catalogue is tires and oil changes. No mechanical work, no diagnostics, no suspension. That narrowness is a gift for a systems person, because it strips away most of the domain noise and leaves a handful of genuinely hard problems. The hardest one is not inventory and it is not scheduling. It is geography. A van leaves a yard, drives to wherever the vehicle is sitting, and does the work in a driveway or a parking lot. Whether we can profitably reach a given address, and how much of the day that address consumes, is the question the whole mobile service operation rests on.

This article is about getting that question right. It walks through why two common models — a postal code allowlist and a radius circle — fail in specific, instructive ways; what the correct geometric primitives are; how to pick a coordinate reference system for Alberta and why the default choice is wrong; what an isochrone actually is under the hood; how to test a point against a polygon at scale without lighting your CPU on fire; and how to store all of it so that a decision made in April can still be explained in September. Every number in the worked examples is illustrative and invented for the purpose of the example. None of them are operating statistics.

The Question Behind the Question

"Can we serve this address" is two questions wearing one coat.

The first is a feasibility question: is the location reachable by a service van within the operating constraints we have set? The second is an economics question: what does reaching it cost in van-minutes, and does that cost fit the job we are being asked to do? A twenty-minute tire rotation ninety minutes away is a loss even if the van can physically get there.

Naive systems answer only the first and pretend the second does not exist. That is how you end up with a dispatcher manually overriding the software every morning, which is the real symptom you are looking for when you audit one of these systems. If humans routinely override the boolean, the boolean is modelling the wrong thing.

The output we actually want is richer than a bit:

Field	Type	Meaning
`covered`	boolean	Reachable under the active policy
`zone_version_id`	uuid	Exactly which polygon produced the answer
`drive_time_band`	enum	`t20`, `t35`, `t50`, `outside`
`confidence`	enum	`geocoded_exact`, `geocoded_interpolated`, `unresolved`
`decided_at`	timestamptz	When the evaluation ran

Once the return type looks like that, most of the design follows. You need polygons with identity, you need versions, and you need a record of what was decided and why.

Postal Codes Are an Addressing Artifact, Not a Geography

A Canadian postal code has the form A1A 1A1. The first three characters form the Forward Sortation Area — the FSA. The last three form the Local Delivery Unit, the LDU. In T2P 1J9, T2P is downtown Calgary and 1J9 narrows it to a specific side of a specific block, or a specific large building, or a specific set of post office boxes.

The second character carries a signal that surprises people: a zero means rural. T0L is rural southwest Alberta. T2P is urban. That single digit is the difference between an FSA covering a few dozen city blocks and an FSA covering an area you could lose a small country in.

Here is the first structural problem. Postal codes are not areas. They are routes. Canada Post assigns them to sequences of delivery points so that a letter carrier or a rural driver can walk or drive them efficiently. The polygon you get when you download an "FSA boundary file" is a derived product — typically built by taking every dissemination block whose addresses carry that FSA and unioning them together. It is a reasonable approximation of where the addresses are. It is not an authoritative statement about where a line sits on the ground, and nobody at Canada Post is maintaining it as one.

The second problem is straddling. Municipal boundaries and postal routes were drawn by different organizations for different reasons and they were never reconciled. T3Z covers Springbank, which is in Rocky View County, west of the city limits. T1X spans Chestermere and reaches into county land around it. T3R includes both far northwest Calgary and acreage subdivisions well outside the city. If your allowlist contains T3Z, you have implicitly promised service to properties scattered across a corridor of foothills, some of which are a pleasant twenty-five minutes away and some of which are up a gravel range road that eats forty minutes in each direction.

The third problem is scale. A rural FSA such as T0M or T0J can cover hundreds of square kilometres. Including it in an allowlist is not a coverage decision; it is a coin flip with the geography.

The fourth problem is time. Calgary builds new communities continuously. When a new neighbourhood goes in, the addresses exist before the postal codes do, and the postal codes exist before anybody updates your spreadsheet. An allowlist written in 2023 is silently wrong about every subdivision occupied since. The failure is invisible: the request arrives, the lookup misses, and the customer is told no. Nothing logs an error, because from the software's perspective nothing went wrong.

The fifth problem is ownership. Ask who maintains the list. In every organization I have seen, the honest answer is "the person who made it, who has since moved to a different role." An unowned lookup table in a repository is technical debt that accrues interest in the form of lost work you never find out about.

A quick summary of what each failure mode costs you:

Failure mode	Symptom	How you find out
Route, not area	Boundary disputes at the edges	Dispatcher overrides
Straddling FSA	Wildly variable travel for one code	Van runs long
Rural FSA scale	Accidental hundred-kilometre promises	Angry driver
New development gap	Silent refusals	Never, usually
No owner	Slow drift from reality	Quarterly panic

The Radius Circle and the Lie of Euclidean Distance

The natural second attempt is a circle. Take the depot coordinates, pick a radius, and test whether the customer's point falls inside. It is one line of code and it feels principled because it is at least about distance.

It is wrong for a reason that has nothing to do with implementation quality: euclidean distance and network distance are different measurements, and the ratio between them is not a constant.

That ratio has a name in transport geography — the circuity ratio, or detour index. In a clean grid with no obstacles it hovers around 1.2 to 1.3. Rivers, rail corridors, and limited-access highways push it much higher in specific places. Calgary has all three. The Bow River cuts through the city from northwest to southeast and the Elbow joins it downtown. Two addresses six hundred metres apart across the Bow can be a seven-kilometre drive if the nearest crossing is inconvenient, and the number of crossings is small relative to the length of the river.

Limited-access roads invert the intuition in the other direction. Deerfoot Trail is a freeway with interchanges, not intersections. You cannot enter it from the adjacent residential street; you enter it where an interchange exists. So a point three hundred metres from a Deerfoot lane may be structurally far from Deerfoot. Meanwhile a location fifteen kilometres up the corridor with an interchange at its doorstep is functionally close.

Stoney Trail, the ring road, does the same thing at city scale. It makes perimeter movement dramatically cheaper than radial movement through the core. A circle drawn around the depot is isotropic — it assumes travel cost grows at the same rate in every direction. The actual cost surface is nothing like that. It is stretched along the freeway corridors and compressed across the river valleys and the rail yards.

There is a second, subtler defect. A circle drawn in degrees is not even a circle. If you write ST_DWithin(depot, customer, 0.35) against geometries in EPSG:4326, the unit is degrees, and a degree of longitude at Calgary's latitude is much shorter than a degree of latitude. Your "circle" is an ellipse squashed east-west by roughly 37 percent. I have found this bug in production more than once, and it never announces itself; it just quietly refuses service to the east and west while over-promising to the north and south.

Anisotropy, Deerfoot, and the 16:45 Problem

Consider two hypothetical service requests, both illustrative:

Request A sits eight kilometres from the yard in a straight line, but on the far side of the core, and the van would have to cross the river and traverse downtown.
Request B sits fifteen kilometres from the yard in a straight line, but almost all of that distance is ring-road running with an interchange at each end.

At 10:30 on a Tuesday these might both be roughly twenty-two minutes. At 16:45 on a Thursday in October, Request A is forty-plus minutes and Request B is still around twenty-five. A radius model ranks A as nearer than B in both scenarios and is therefore wrong exactly when being wrong is most expensive — during the afternoon peak of the autumn changeover, when the seasonal swap rush has every slot in the day already committed.

This is anisotropy: cost depends on direction, not just magnitude. And it is non-stationary: the anisotropy field itself changes through the day. Any model that collapses to a single scalar radius has thrown away both properties.

The right abstraction is a level set of the travel-time function. Fix the origin, fix the departure time, fix the vehicle profile, and ask: what is the set of all points reachable within t minutes? That set is a polygon. It is lumpy, it has fingers running along the freeways, it has bites taken out of it where the river blocks movement, and it changes shape depending on when you ask. That polygon is an isochrone, and it is the honest answer.

Geometry Primitives You Actually Need

Before writing anything spatial, fix the vocabulary. The OGC Simple Features model gives you a small set of types and you will use four of them.

A Point is a coordinate pair. In a geographic system it is (longitude, latitude) in that order — which is the reverse of how humans say it, and the source of a truly enormous number of bugs. GeoJSON, PostGIS, and most routing APIs use x-then-y. Leaflet's LatLng does not. Write a single conversion helper and never do it inline.

A LineString is an ordered sequence of points. Roads are linestrings. Your depot-to-customer path is a linestring. Nothing about it is closed.

A Polygon is one exterior ring plus zero or more interior rings, where a ring is a closed linestring whose first and last coordinates are identical. Interior rings are holes. A service zone with a genuine exclusion — a military reserve, a large restricted industrial site — is a polygon with a hole, not two polygons.

A MultiPolygon is a set of disjoint polygons treated as one geometry. This is what you actually want for a service zone, because real coverage is often disconnected. A town twenty minutes down the highway with nothing serviceable in between is a separate part of the same zone.

Winding order deserves its own paragraph because it will eventually cost you a day. RFC 7946, the GeoJSON specification, requires exterior rings to be counterclockwise and interior rings clockwise — the right-hand rule. The Esri shapefile format uses the opposite convention for exteriors. PostGIS mostly does not care, because it treats rings as planar and infers holes from containment. Spherical geometry libraries such as S2, and by extension several cloud data warehouses, care intensely: on a sphere a ring divides the surface into two finite regions, and orientation is the only thing that tells you which one you meant. Get it backwards and your Calgary service zone becomes "the entire planet except Calgary." The symptom is unmistakable once you have seen it, and baffling the first time.

Two invariants worth asserting on ingest:

The geometry is valid under OGC rules. Self-intersecting exterior rings are the usual offender; ST_IsValid plus ST_IsValidReason will name the problem, and ST_MakeValid will usually fix it at the cost of silently changing your data.
Ring orientation is normalized. ST_ForcePolygonCCW on the way in means downstream consumers never have to guess.

Choosing a Coordinate Reference System for Alberta

EPSG:4326 is WGS 84, a geographic coordinate system whose units are degrees of angle. It is the right storage and interchange format. It is the wrong computation format for anything involving length or area, and the reason is straightforward: a degree is not a distance.

At Calgary's latitude, roughly 51.05 degrees north, one degree of latitude is about 111.2 kilometres. One degree of longitude is that same figure scaled by the cosine of the latitude — about 0.629 — giving roughly 70.0 kilometres. So the coordinate grid is anisotropic by a factor of 1.59 before you have done anything at all. Any planar distance, area, or buffer computed on raw lat/lon inherits that distortion.

The three ways out, in ascending order of how much I like them:

Use geography types. PostGIS geography computes on the spheroid and returns metres. ST_DWithin(a::geography, b::geography, 25000) is correct and readable. The cost is that the geography operator set is narrower and the functions are slower, sometimes considerably, on complex polygons.

Use Web Mercator. Do not. EPSG:3857 is a presentation projection. Its scale factor is the secant of the latitude, so at 51 degrees north every length is inflated by about 1.59 and every area by about 2.53. It exists so that map tiles are square. It has no business in a measurement pipeline, and the fact that it is the default in several visualization stacks has produced a lot of quietly wrong analytics.

Use a local projected CRS. This is the right answer for repeated planar work. The question is which one.

The obvious candidate is UTM. Calgary sits at about 114.07 degrees west, which places it in UTM zone 11N, EPSG:32611 — but only just. The boundary between zone 11 and zone 12 runs along the 114th meridian, roughly seven kilometres east of downtown. So the moment your service area extends east toward Chestermere at 113.7 west or Strathmore at 113.4 west, you are working across a zone boundary. You can force everything into zone 11 and accept the extrapolated distortion; near the zone edge the scale factor drifts to roughly 1.001, which is a metre per kilometre. Over a forty-kilometre run that is forty metres of error. Tolerable for coverage decisions, irritating for anything else, and philosophically unsatisfying.

Alberta publishes a better option. The provincial 3TM system uses three-degree-wide transverse Mercator zones with central meridians at 111, 114, 117, and 120 degrees west, and — critically — a scale factor of exactly 1.0 at the central meridian rather than UTM's 0.9996. The 114 W zone spans 112.5 to 115.5 degrees west, which comfortably contains Cochrane, Airdrie, Calgary, Okotoks, Chestermere, and Strathmore in a single undistorted frame with the central meridian running essentially through the city.

That definition is commonly catalogued as EPSG:3401 for the NAD83 datum, with NAD83(CSRS) realizations in the neighbouring 3775–3779 block. Verify against your own PROJ installation rather than trusting a number from an article — projinfo EPSG:3401 will print the WKT and you can confirm the central meridian yourself. Getting the datum realization wrong is a sub-metre error and usually irrelevant for coverage; getting the central meridian wrong is not.

A comparison of the candidates on the axes that matter:

CRS	Units	Distortion near Calgary	Verdict
EPSG:4326	degrees	n/a — not planar	Storage and interchange
EPSG:3857	metres	~1.59x length, ~2.53x area	Tiles only
EPSG:32611	metres	~1.001 near zone edge	Workable, awkward east
Alberta 3TM 114 W	metres	~1.0 across the region	Preferred for planar math
`geography`	metres	spheroidal, correct	Good default when speed allows

My standing recommendation: store in 4326, index in 4326, and reproject to the 3TM 114 W frame inside any function that buffers, measures, or computes area. Keep the reprojection at one boundary in the code so it is auditable.

What an Isochrone Really Is

An isochrone is a contour of the travel-time field. The definition is clean; the construction is not, and understanding the construction tells you what to distrust.

A routing engine — Valhalla, OSRM with a custom profile, GraphHopper, pgRouting over an imported network — holds the road network as a directed graph. Nodes are intersections, edges are road segments, and each edge carries a traversal cost derived from length, classification, speed data, turn restrictions, and access rules for the vehicle profile.

To build a fifteen-minute isochrone the engine runs a single-source shortest-path expansion from the origin, typically Dijkstra with a cost ceiling instead of a target node. It stops expanding when accumulated cost exceeds the budget. What comes back is not a polygon; it is a labelled subgraph — every node with its minimum cost from the origin.

Turning that into an area requires interpolation. Valhalla's approach is representative: it rasterizes costs onto a regular grid, assigning each cell the lowest cost reachable within it, then runs marching squares over that grid to extract the iso-cost contour, then generalizes and polygonizes the result. Every step of that pipeline introduces artifacts:

Grid resolution determines how faithfully narrow features survive. A single road threading through otherwise unreachable terrain may be widened into a lobe or dropped entirely.
Generalization trades vertex count for fidelity. A polygon with two hundred vertices tests fast and lies a little. One with twenty thousand vertices tests slowly and lies less.
Holes appear where an enclosed area is genuinely unreachable within the budget, and also where the grid was too coarse to notice the road that reaches it.

Time-of-day dependence is the property people forget. If the engine is running free-flow speeds derived from road classification, the polygon describes an empty city at three in the morning. Valhalla accepts a departure timestamp and will use predicted traffic if you have loaded a traffic tile set. OSRM has no native concept of time; the usual workaround is to compile separate graphs with per-bucket speed tables and route against whichever matches the hour. Either way, the polygon is a function of (origin, budget, profile, departure_bucket, graph_version), and if your cache key omits any of those, you will eventually serve an answer generated for a different world.

Versioning and Caching Drive-Time Polygons

Generating isochrones on the request path is a mistake. It is a network hop to a service that is doing a graph expansion and a contouring pass, and it puts a third-party dependency in the latency budget of something a customer is waiting on.

Generate them offline. A batch job runs per origin, per budget, per departure bucket, writes the resulting geometry into the database with full provenance, and marks it active. Coverage evaluation then reads a local polygon and never touches the routing engine.

The provenance record should be complete enough to regenerate the exact polygon:

{
  "origin": {"lon": -114.0719, "lat": 51.0447},
  "cost_seconds": 1800,
  "profile": "auto",
  "departure_bucket": "weekday_pm_peak",
  "engine": "valhalla",
  "engine_version": "3.4.0",
  "graph_extract": "alberta-2026-07-14.osm.pbf",
  "generalize_m": 40,
  "denoise": 0.2,
  "generated_at": "2026-07-15T04:12:08Z"
}

Three rules keep this honest.

First, versions are immutable. You never update a geometry in place. A new generation writes a new row with a new version number and a validity window; the old row stays exactly as it was. This is what makes historical explanation possible, and it is worth every byte.

Second, the cache key is the full provenance tuple, not the origin alone. I have watched a team spend a day debugging "the polygon changed by itself" when in fact two jobs with different departure buckets were writing to the same key.

Third, regeneration is scheduled against the graph extract, not the calendar. When the OpenStreetMap extract updates and the network topology changes — a new interchange opens, a bridge closes for construction — the polygons are stale regardless of how recently you rebuilt them. Tie the trigger to the input, not to a cron expression that somebody picked arbitrarily.

Point in Polygon: Ray Casting, Winding Numbers, and the Gap Between Them

Given a polygon and a point, decide containment. Two classical algorithms, both O(n) in the vertex count, both worth understanding before you delegate to a library.

Ray casting, also called the crossing number or even-odd rule, shoots a ray from the query point in a fixed direction — conventionally along positive x — and counts how many polygon edges it crosses. Odd means inside, even means outside. It is four lines of arithmetic per edge and it is what most naive implementations use.

Winding number computes how many times the polygon boundary wraps around the point, summing signed angles or, more practically, using orientation tests on each edge. Nonzero means inside.

For a simple, non-self-intersecting polygon the two agree everywhere. They diverge on self-intersecting geometry: a figure-eight's crossover lobe is outside under even-odd and inside under nonzero winding. Real isochrone output is not always clean, especially after generalization, so this is not purely academic. My preference is to validate and repair geometries on ingest so that the question never arises, and then use whichever predicate the library implements — but to know which one that is.

Complexity matters once you have more than a couple of zones. The naive loop is O(Z·n) for Z zones averaging n vertices. With a dozen active zone versions at a few thousand vertices each, a single evaluation touches tens of thousands of edges. At a few hundred requests a minute that is measurable, and it is entirely avoidable.

Spatial Indexes and the Bounding-Box Prefilter

The fix is the standard two-phase spatial query: cheap filter, then exact refinement.

Phase one uses an R-tree. Every geometry contributes its minimum bounding rectangle to a balanced tree of nested rectangles. A point query descends the tree and returns the small set of candidates whose MBR contains the point. That is O(log Z) expected, and it eliminates the overwhelming majority of zones with four float comparisons each.

Phase two runs the exact predicate on the survivors only. If your zones are roughly convex and well separated, phase one usually leaves one candidate. If they are long and diagonal — a corridor along a highway is the classic case — the MBR is a poor approximation and you will get more false positives, which is an argument for splitting a straggly zone into a MultiPolygon of tighter parts.

PostGIS gives you this for free. A GIST index over a geometry column is an R-tree over the bounding boxes, implemented on top of the generalized search tree framework. The && operator is bounding-box overlap and is index-accelerated. Functions like ST_Contains and ST_Intersects are defined as && composed with the exact underscore-prefixed predicate, so the planner uses the index automatically. What is not automatic: an index on geom does nothing for a query that wraps the column in ST_Transform. Either index the expression or store a second projected column.

Shapely's STRtree is a packed Sorted-Tile-Recursive R-tree — built once, queried many times, not modifiable afterwards. That fits the isochrone workload exactly, because zone versions change on a batch schedule rather than per request.

One more trick worth its weight: prepared geometries. Both GEOS and Shapely can precompute an edge index for a polygon that will be tested repeatedly. shapely.prepared.prep returns an object whose contains is dramatically faster on high-vertex polygons after the first invocation. Build them once at index construction and hold them for the process lifetime.

A Data Model That Can Explain Itself Later

Here is the schema I would defend in review. PostGIS 3.x, PostgreSQL 15 or newer.

CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS btree_gist;

CREATE TABLE service_zones (
    id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    slug          text NOT NULL UNIQUE,
    display_name  text NOT NULL,
    zone_kind     text NOT NULL CHECK (zone_kind IN ('drive_time','manual','union')),
    depot_id      uuid NOT NULL REFERENCES depots(id),
    notes         text,
    created_at    timestamptz NOT NULL DEFAULT now()
);

The zone is an identity and a policy statement. It carries no geometry, because the geometry changes and the identity does not.

CREATE TABLE zone_versions (
    id              uuid PRIMARY KEY DEFAULT gen_random_uuid(),
    zone_id         uuid NOT NULL REFERENCES service_zones(id),
    revision        integer NOT NULL,
    geom            geometry(MultiPolygon, 4326) NOT NULL,
    geom_3tm        geometry(MultiPolygon, 3401)
                    GENERATED ALWAYS AS (ST_Transform(geom, 3401)) STORED,
    source_kind     text NOT NULL,
    provenance      jsonb NOT NULL,
    cost_seconds    integer,
    departure_bucket text,
    validity        tstzrange NOT NULL,
    authored_by     text NOT NULL,
    created_at      timestamptz NOT NULL DEFAULT now(),
    UNIQUE (zone_id, revision),
    CONSTRAINT geom_is_valid CHECK (ST_IsValid(geom)),
    CONSTRAINT no_overlapping_windows
        EXCLUDE USING gist (zone_id WITH =, validity WITH &&)
);

CREATE INDEX zone_versions_geom_gix ON zone_versions USING GIST (geom);
CREATE INDEX zone_versions_live_idx ON zone_versions USING GIST (validity);

Three things in that definition are doing real work. The generated projected column means planar measurement never pays a runtime transform and the index on it stays usable. The CHECK (ST_IsValid(geom)) constraint refuses malformed contour output at the door rather than three weeks later during an incident. The exclusion constraint — which needs btree_gist to mix an equality column with a range column — makes it structurally impossible for one zone to have two simultaneously active versions. That single line removes an entire category of ambiguity from the system.

CREATE TABLE coverage_checks (
    id                 bigserial PRIMARY KEY,
    requested_at       timestamptz NOT NULL DEFAULT now(),
    raw_address        text NOT NULL,
    normalized_address text,
    geocoder           text,
    geocode_quality    text NOT NULL,
    point              geometry(Point, 4326),
    zone_version_id    uuid REFERENCES zone_versions(id),
    decision           text NOT NULL
                       CHECK (decision IN ('covered','outside','undetermined')),
    decision_reason    text NOT NULL,
    boundary_margin_m  double precision,
    served_from_cache  boolean NOT NULL DEFAULT false,
    latency_ms         integer NOT NULL
);

CREATE INDEX coverage_checks_point_gix ON coverage_checks USING GIST (point);
CREATE INDEX coverage_checks_recent_idx
    ON coverage_checks (requested_at DESC)
    INCLUDE (decision, zone_version_id);

The foreign key from a check to a version is the whole point of the design. Someone reviewing a job from four months ago asks why the system said yes to an address it now says no to. Without that column the answer is an archaeology project. With it, you join two tables and print the polygon that was live at the time, alongside the provenance blob describing which graph extract and which departure bucket produced it. boundary_margin_m earns its place too — the distance to the nearest boundary tells you whether a decision was comfortable or a coin flip, and aggregating it reveals where the polygon needs attention.

Queries Worth Writing Down

Which zones cover a point right now, ordered by tightest drive-time budget:

SELECT z.slug, zv.id AS version_id, zv.cost_seconds
FROM zone_versions zv
JOIN service_zones z ON z.id = zv.zone_id
WHERE zv.validity @> now()
  AND zv.geom && ST_SetSRID(ST_MakePoint($1, $2), 4326)
  AND ST_Intersects(zv.geom, ST_SetSRID(ST_MakePoint($1, $2), 4326))
ORDER BY zv.cost_seconds ASC
LIMIT 1;

The && clause is redundant in the sense that ST_Intersects already applies it, but writing it explicitly documents the intent and survives refactors where somebody swaps the predicate for one that is not index-backed.

How far is this point from the edge of the zone, in metres:

SELECT ST_Distance(
         ST_Transform(ST_SetSRID(ST_MakePoint($1, $2), 4326), 3401),
         ST_Boundary(zv.geom_3tm)
       ) AS margin_m
FROM zone_versions zv
WHERE zv.id = $3;

Note the transform on the point and the pre-projected column on the polygon. Doing it the other way — transforming the polygon per row — is the single most common performance mistake in PostGIS code I review.

Area of a zone in square kilometres, which is a sanity check you should run on every generated version:

SELECT z.slug,
       zv.revision,
       round((ST_Area(zv.geom_3tm) / 1e6)::numeric, 1) AS area_km2
FROM zone_versions zv
JOIN service_zones z ON z.id = zv.zone_id
WHERE zv.validity @> now()
ORDER BY area_km2 DESC;

If a regeneration changes the area by more than a threshold you have chosen — twenty percent is a reasonable illustrative starting point — that is a signal, not a routine event. Something upstream moved. Hold the new version in a staging state and make a human look at it before it goes live.

Python: Prefilter, Exact Test, and a Ray Caster for Teaching

Production code should use Shapely and let GEOS do the arithmetic. Here is the structure I use, with the two-phase filter made explicit rather than hidden.

from dataclasses import dataclass
from typing import Optional, Sequence

from shapely.geometry import Point, shape
from shapely.geometry.base import BaseGeometry
from shapely.prepared import prep
from shapely.strtree import STRtree


@dataclass(frozen=True)
class ZoneVersion:
    version_id: str
    slug: str
    cost_seconds: int
    geometry: BaseGeometry


@dataclass(frozen=True)
class Verdict:
    covered: bool
    version_id: Optional[str]
    reason: str


class CoverageIndex:
    """Immutable spatial index over the zone versions live at build time."""

    def __init__(self, versions: Sequence[ZoneVersion]):
        self._versions = list(versions)
        self._geoms = [v.geometry for v in self._versions]
        self._prepared = [prep(g) for g in self._geoms]
        self._bounds = [g.bounds for g in self._geoms]
        self._tree = STRtree(self._geoms)
        self._position = {id(g): i for i, g in enumerate(self._geoms)}

    def _bbox_hit(self, idx: int, lon: float, lat: float) -> bool:
        minx, miny, maxx, maxy = self._bounds[idx]
        return minx <= lon <= maxx and miny <= lat <= maxy

    def evaluate(self, lon: float, lat: float) -> Verdict:
        probe = Point(lon, lat)
        candidates = self._tree.query(probe)
        if len(candidates) == 0:
            return Verdict(False, None, "no_bbox_candidate")

        hits = []
        for candidate in candidates:
            idx = self._resolve(candidate)
            if not self._bbox_hit(idx, lon, lat):
                continue
            if self._prepared[idx].contains(probe):
                hits.append(self._versions[idx])

        if not hits:
            return Verdict(False, None, "bbox_hit_exact_miss")

        best = min(hits, key=lambda v: v.cost_seconds)
        return Verdict(True, best.version_id, f"inside:{best.slug}")

    def _resolve(self, candidate) -> int:
        if isinstance(candidate, (int,)):
            return int(candidate)
        return self._position[id(candidate)]

The _resolve shim exists because Shapely 2.0 changed STRtree.query to return integer indices where 1.8 returned geometry objects. If you maintain a library that must span both, hide the difference in one place.

Now the pedagogical version. Nobody should ship this, but everybody who works on spatial systems should be able to write it from memory, because when a library gives you an answer you do not believe, this is how you find out who is wrong.

def point_in_ring(x: float, y: float, ring: Sequence[tuple]) -> bool:
    """Crossing-number test with a half-open edge rule.

    The ring is a closed sequence of (x, y) pairs. The half-open
    comparison (yi > y) != (yj > y) treats each edge as containing
    its lower endpoint and excluding its upper one, which makes a
    ray that passes exactly through a vertex count once, not twice
    and not zero times.
    """
    inside = False
    count = len(ring)
    j = count - 1
    for i in range(count):
        xi, yi = ring[i]
        xj, yj = ring[j]
        if (yi > y) != (yj > y):
            t = (y - yi) / (yj - yi)
            crossing_x = xi + t * (xj - xi)
            if crossing_x > x:
                inside = not inside
        j = i
    return inside


def point_in_polygon(x, y, exterior, holes=()) -> bool:
    if not point_in_ring(x, y, exterior):
        return False
    return not any(point_in_ring(x, y, hole) for hole in holes)

The half-open rule in that conditional is the entire trick. A naive implementation writes yi <= y < yj or yj <= y < yi and gets it right by accident; an implementation that writes min(yi, yj) <= y <= max(yi, yj) double-counts vertex hits and returns the wrong parity for any point whose latitude exactly matches a vertex. Since isochrone vertices come out of a regular grid, and grid latitudes are extremely round numbers, that case is far more common than a uniform-random model would predict.

Floating Point on the Boundary

Three degenerate cases, and what to do about each.

The point lies exactly on an edge. Mathematically the predicate is undefined unless you state a convention. Computationally, whether it lands on the edge depends on whether t and crossing_x round the way you hoped. Decide the policy explicitly — boundary counts as inside is the humane choice for a service area — and implement it as a separate test rather than hoping the crossing count works out. In PostGIS that means ST_Covers rather than ST_Contains; ST_Contains returns false for boundary points and ST_Covers returns true, and confusing the two produces a bug that appears roughly one time in ten thousand and is never reproducible on demand.

The ray passes through a vertex. Handled by the half-open rule above. Verify it with a fixture: a point at exactly the same y as a polygon vertex, once with the vertex to the left and once to the right.

Two computations disagree. This is the one that ruins afternoons. The same address evaluated twice returns different answers because one path went through a projection and the other did not, or because a value round-tripped through JSON at fifteen significant digits instead of seventeen. Determinism is a property you have to engineer.

Three practices buy it:

Snap on ingest. ST_SnapToGrid(geom, 1e-7) quantizes coordinates to about 1.1 centimetres of latitude. Every downstream computation then starts from the same numbers, and the crossing arithmetic becomes reproducible across library versions.
Serialize with full precision. ST_AsGeoJSON(geom, 15) and a JSON encoder that does not truncate. A double needs 17 significant decimal digits for a lossless round trip; most defaults give you fewer.
Refuse to answer near the boundary. Compute the margin. If the point sits within a tolerance band of the edge — five metres is a defensible illustrative choice — return undetermined and let a human resolve it. This is not a cop-out. It is an honest statement that the polygon's own accuracy is coarser than the question being asked, and it converts a silent wrong answer into a visible, countable event.

Underneath all of this, if you need genuinely exact orientation tests, the answer is adaptive-precision arithmetic — Shewchuk's robust predicates, which JTS implements with double-double arithmetic and GEOS inherits. Knowing it exists is usually enough; needing it means your tolerances are wrong.

Geocoding Failures and Failing Closed

Coverage evaluation has a dependency most designs underweight: turning text into coordinates. If geocoding is wrong, everything downstream is confidently wrong.

Calgary makes this harder than average because of quadrants. The city is divided into NW, NE, SW, and SE, and street numbering restarts in each. "123 5 Street" is four different places. A form that lets a customer omit the quadrant, or a normalizer that drops it, will hand the geocoder an ambiguous string, and the geocoder will pick one — usually the most populous match, usually silently. The van is then dispatched to a location twelve kilometres from the vehicle. Quadrant is not optional metadata; treat a missing quadrant as a validation failure and resolve it before geocoding.

The normalizer should also handle unit designators, since a driveway visit needs the building and a bay number needs the unit; the abbreviation zoo of ST, AV, DR, CR, BV, TR, WY, GA, LI, PZ; and directional suffixes that some sources write as N.W. and others as NW.

Then fail closed. Every geocoder returns a quality signal, and the tiers matter:

Quality	Meaning	Policy
Rooftop / parcel	Resolved to the property	Evaluate normally
Interpolated	Estimated along a street segment	Evaluate, widen the margin band
Street centroid	Street matched, number did not	Undetermined, route to review
Locality only	City or town matched	Undetermined
No match	Nothing	Undetermined

An interpolated result on a long rural road can be hundreds of metres off, which is exactly where the polygon edge tends to be. Treating "interpolated" as equivalent to "rooftop" is a quiet source of bad dispatches, and the correction is small: multiply the boundary tolerance by the positional uncertainty of the geocode tier.

Failing closed means an unresolved address never returns covered. It returns undetermined with a reason code, and something in the workflow — a queue, a flagged record, a note on the service request — routes it to a person. Customers near a boundary are also frequently near an edge case in the data, and rural addresses on range roads are both. For a business whose service area genuinely extends past the city limits, that queue is not an exception path; it is a normal part of Tuesday.

Caching on Rounded Coordinates

Once volume grows, evaluating the same location repeatedly is waste. The obvious cache key is the coordinate pair, and the obvious refinement is to round it so that near-identical points share an entry.

Round to four decimal places and, at Calgary's latitude, a cell is roughly 11.1 metres north-south by 7.0 metres east-west. Five decimals gives about 1.1 by 0.7 metres. The tradeoff is direct: coarser cells mean a higher hit rate and a larger maximum positional error introduced by the key itself.

The failure mode is specific. If a rounding cell straddles a zone boundary, two genuinely different addresses collapse to one key, and whichever was evaluated first determines the answer for both. One of them is wrong, and the record shows a clean, plausible, cached decision.

The mitigation is to make cacheability conditional on the margin you already compute:

CELL_DEG = 1e-4
CELL_DIAGONAL_M = 13.2  # illustrative, at ~51 deg N


def cache_key(lon: float, lat: float, policy_id: str) -> str:
    qx = round(lon / CELL_DEG)
    qy = round(lat / CELL_DEG)
    return f"cov:{policy_id}:{qx}:{qy}"


def maybe_store(result, margin_m: float) -> bool:
    if result.reason == "undetermined":
        return False
    return margin_m is not None and margin_m > CELL_DIAGONAL_M

Comfortable decisions get cached; marginal ones are recomputed every time. Since the marginal population is small, the hit rate barely moves and the correctness problem disappears. Include the policy or zone-set identifier in the key so that publishing a new zone version invalidates by construction rather than by remembering to flush.

When the Routing Provider Is Down

Because isochrones are precomputed, a routing outage cannot break coverage evaluation. That is most of the value of the offline design, and it is worth stating explicitly to whoever is reviewing the architecture.

What an outage does break is regeneration, and the failure is quiet. Polygons drift out of date, nothing alarms, and three weeks later somebody notices the new interchange is not represented. Alert on generation age, not on generation errors.

For the routing that does happen live — estimating travel time to a specific address so a dispatcher can size the day — build a ladder:

Primary. The routing engine with a strict timeout. Two seconds is a reasonable illustrative ceiling for an interactive path.
Secondary. A cached matrix of depot-to-cell travel times at a coarse grid resolution. Stale by hours, accurate within a few minutes, and available instantly.
Tertiary. Straight-line distance multiplied by a direction-dependent circuity factor derived from historical data. Crude, but it degrades gracefully and it is better than an error page.
Floor. Return the polygon-based coverage verdict with the estimate marked provisional, and let the human decide.

Each tier tags its output with the method used, and that tag lands in the service record. When you later analyze which estimates were poor, you can separate "the model is bad" from "the model was not running."

The same discipline applies to the geocoder. A second provider behind a circuit breaker costs a day to integrate and removes a single point of failure from the most upstream step in the chain. For urgent work — a flat repair on a vehicle stranded in a lot, or the kind of roadside situation where minutes are the whole story — a degraded answer delivered now beats a perfect answer delivered after the customer has given up.

Testing Coverage Without Brittleness

Spatial tests fail badly when written naively, because the natural assertion — "this coordinate is inside this polygon" — breaks whenever the polygon is regenerated, which is often. The tests then get deleted, and coverage logic ends up with the worst test suite in the codebase despite being one of its riskiest components.

Three layers that hold up.

Golden points. A fixture file of coordinates with expected verdicts and a human-written rationale. Choose points that are unambiguous by construction — deep inside the core, well outside in open country, on the far side of an obvious barrier — not points scraped from a map near an edge.

GOLDEN = [
    ("depot_yard",        -114.0719, 51.0447, "covered"),
    ("inner_city_core",   -114.0630, 51.0450, "covered"),
    ("north_ring_edge",   -114.0100, 51.1800, "covered"),
    ("far_east_prairie",  -112.4000, 50.9500, "outside"),
    ("mountain_park",     -116.0300, 51.1700, "outside"),
]

Assert the verdict and the reason code. If a regeneration flips a golden point, the build fails and a person looks at the polygon — which is the outcome you want.

Property tests. These survive polygon churn because they assert invariants rather than facts. The most valuable one is projection stability: reproject a point from 4326 into the working CRS and back, and require that the containment verdict is unchanged and the coordinate agrees to within a tight tolerance.

from hypothesis import given, strategies as st
from pyproj import Transformer

FWD = Transformer.from_crs("EPSG:4326", "EPSG:3401", always_xy=True)
INV = Transformer.from_crs("EPSG:3401", "EPSG:4326", always_xy=True)


@given(
    lon=st.floats(min_value=-115.4, max_value=-112.6),
    lat=st.floats(min_value=49.8, max_value=52.2),
)
def test_reprojection_round_trip_preserves_verdict(lon, lat):
    x, y = FWD.transform(lon, lat)
    lon2, lat2 = INV.transform(x, y)
    assert abs(lon2 - lon) < 1e-9
    assert abs(lat2 - lat) < 1e-9
    assert INDEX.evaluate(lon, lat).covered == INDEX.evaluate(lon2, lat2).covered

Other invariants that pay for themselves: every stored geometry is valid; no two active versions of one zone overlap in time; a point inside a tighter drive-time band is inside every looser band from the same origin; and the same input evaluated twice in one process yields byte-identical output.

Boundary tests without brittleness. Do not assert what happens on the line. Assert monotonicity around it. Take a boundary vertex, step fifty metres along the inward normal, and require covered. Step fifty metres outward and require not covered. Between those, require only that the answer is stable and that the margin computation reports a value below the tolerance. You are testing the shape of the decision function rather than the coordinates of the polygon, which is what you actually care about.

One more thing worth automating: an area-delta check between consecutive versions, run in CI against a fixture polygon set. Contouring parameters get tuned, somebody changes a generalization value, and the polygon quietly loses a limb. A percentage-change assertion catches it in the pipeline instead of in dispatch.

Seasonality as a Time-Windowed Zone Version

Alberta has two weeks in spring and two in fall when the entire province changes its tires at once. Demand during the changeover peak is a different distribution from the rest of the year, not merely a larger one, and it breaks any assumption that coverage is a static property.

The arithmetic is unforgiving. A van that completes a fixed number of jobs a day at forty minutes of driving between them completes meaningfully fewer than one averaging twenty. During peak weeks the marginal long-distance job does not add revenue; it removes two closer jobs from the day. So the rational operating policy is a smaller effective service area precisely when demand is highest.

The wrong way to implement that is to edit the polygon. Somebody opens the geometry, shrinks it, and in April somebody else expands it again. History is destroyed, the audit trail lies, and a service record from March cannot be explained.

The right way is a second zone version with a bounded validity window, competing for the same zone identity:

INSERT INTO zone_versions (
    zone_id, revision, geom, source_kind, provenance,
    cost_seconds, departure_bucket, validity, authored_by
)
VALUES (
    :zone_id,
    (SELECT COALESCE(MAX(revision), 0) + 1
       FROM zone_versions WHERE zone_id = :zone_id),
    ST_Multi(ST_GeomFromGeoJSON(:geojson)),
    'isochrone',
    :provenance::jsonb,
    1500,                          -- 25 minutes, tightened from 30
    'weekday_pm_peak',
    tstzrange('2026-10-05 00:00+00', '2026-10-26 00:00+00', '[)'),
    'seasonal-policy-job'
);

The exclusion constraint enforces the rest. If the peak window overlaps the standing version's window, the insert fails, and you are forced to close the standing window explicitly rather than creating a silent ambiguity. That is the constraint doing its job: converting a policy question into a schema error at the moment somebody tries to be careless.

A few consequences fall out of this design that I did not anticipate the first time:

Quotes issued before the window opens must be honoured against the version live at issue time, which means the quote stores a zone_version_id and the fulfilment path reads it rather than re-evaluating.
The tightened polygon is a different isochrone, not a scaled copy. Regenerate it with the peak departure bucket; a negative buffer of the standing polygon shrinks it uniformly, which is exactly the isotropic mistake the whole model exists to avoid.
Announcing the window in advance is cheaper than declining requests during it. Whatever surfaces coverage to customers — the self-serve scheduling page, a dispatcher's screen — should read the version that will be live on the requested date, not the one live right now.

The same mechanism handles other temporal policies without new machinery: a reduced winter zone when a road closes seasonally, an expanded window when a second van joins the rotation, a temporary exclusion around a construction detour. Every one of them is a row with a validity range, and every one of them is explainable afterward.

Latency, Monitoring, and What to Alert On

Coverage evaluation sits on an interactive path, so it needs a latency budget and observability that matches.

The realistic decomposition for a cold request:

Stage	Typical share	Notes
Address normalization	small	Pure CPU, string work
Geocoding	dominant	Network, external provider
Index query and exact test	small	Microseconds with prepared geometry
Margin computation	small	One projected distance
Persisting the check record	small	Single insert, can be async

Geocoding is the entire story. Everything else is noise. That has two implications: cache geocodes aggressively and separately from coverage verdicts, since a normalized address maps to a coordinate far more stably than a coordinate maps to a verdict; and instrument the provider call with its own timer so a provider slowdown is not misattributed to your spatial code.

Metrics I would page on, or at least chart on a wall:

p50, p95, and p99 end-to-end evaluation latency, split by cache-hit status. Averaging across both hides everything.
Geocode failure rate by tier. A rise in "street centroid" results usually means a normalizer regression, not a provider problem.
The undetermined rate. This is your honesty metric. A sudden climb means the geocoder degraded or a new polygon has a boundary running through a populated area.
Boundary-margin distribution. If a large share of requests cluster within a few hundred metres of an edge, the polygon is drawn through demand rather than around it, and the budget should move.
Decision-flip rate across version transitions. Replay a recent sample of points against the incoming version before it goes live; a flip count outside the expected range blocks publication.
Age of the newest zone version per origin, compared against the age of the graph extract.

That last one has caught more real problems than the rest combined, because stale geometry produces answers that look completely normal.

What I Would Build Differently

Three things I got wrong on the first pass, offered as a shortcut past them.

I started with a single polygon per origin and a boolean verdict. Bands should have existed from the beginning. The moment dispatch wants to sequence a day, "inside" is not enough information; they need the drive-time tier, and retrofitting bands meant reworking every consumer. Model concentric budgets — twenty, thirty-five, fifty minutes — from the start, and let the boolean be a derived view over the innermost band that policy currently accepts.

I treated the peak-season constraint as an operational note rather than a data-model requirement. It is a data-model requirement. Anything that changes coverage over time belongs in the versioning mechanism, and discovering that in the middle of an October rush is an unpleasant way to learn it.

I under-invested in the undetermined path. The first version had two outcomes, and every ambiguous case was forced into one of them, which meant the system was confidently wrong at exactly the addresses where being wrong mattered most — acreages, new subdivisions, rural routes. A third state plus a review queue turned an invisible error rate into a visible work item, and the work item turned out to be small.

The broader lesson generalizes past tires. A service area is not a fact about your business; it is a model of a cost surface that changes with the road network, the hour, the season, and the number of vehicles you are running. Postal codes model none of that. A radius models one dimension of it badly. Versioned isochrones with explicit provenance model most of it, and — more importantly — they tell you when they are unsure.

If you want to see the shape of the real-world constraints this design is serving, the operational side is documented plainly: the fleet programs that drive most of the multi-vehicle routing, the commercial work that pushes the polygon outward toward industrial parks, and the Calgary yard that anchors every isochrone in this article. The software exists to answer one question honestly, and the geometry is how it does that.

Parsing Tire Size Codes: Building a Fitment Data Model That Survives Real-World Inputs

KMJ Tire Calgary — Thu, 06 Aug 2026 16:12:50 +0000

Parsing Tire Size Codes: Building a Fitment Data Model That Survives Real-World Inputs

A tire size designation looks trivial until you try to parse one that a human typed. P215/60R16 94H reads like a product code, and most developers who encounter it for the first time reach for a single regular expression, ship it, and move on. Then the intake queue delivers LT265/70R17 121/118S E, followed by 35x12.50R17, followed by 225 60 16 pasted from a text message, followed by 2256016 with no separators at all, and the single regex becomes a graveyard of nested optional groups that nobody on the team wants to touch.

I work on the software side of KMJ Tire, a small Calgary operation that handles tire work and oil changes and nothing else — no mechanical repair, no diagnostics, just rubber, wheels, and lubricant. That narrow scope means our data problems are narrow too, and the deepest one is fitment: given a string a customer typed into a web form or a size a technician read off a sidewall, what tire is actually being described, does it fit the vehicle in question, and is it safe relative to what the manufacturer specified? This article walks through the grammar of tire sizes, a tokenizer and parser that handle the real-world mess, a normalized data model, the diameter math behind equivalence and plus-sizing, and the validation layer that refuses dangerous fitments. All code is Python and runnable in spirit; illustrative examples are labelled as such, and none of the numbers here are business statistics.

A Sidewall Is a Grammar, Not a String

The designation moulded into a sidewall is a compact sentence in a formal language. P215/60R16 94H decomposes into:

P — an optional service-type prefix (P for passenger, LT for light truck, T for temporary spare, ST for special trailer, C suffix conventions in Europe).
215 — section width in millimetres, the widest point of the inflated tire.
60 — aspect ratio, sidewall height as a percentage of section width.
R — internal construction (R radial, D diagonal/bias, B belted bias). You will also meet ZR, which historically encoded a speed capability above 240 km/h and still appears combined with a modern speed symbol.
16 — rim diameter in inches. Yes, the same designation mixes millimetres, percentages, and inches. This is the industry standard and it is never going away.
94 — load index, an integer that maps through a standardized table to a maximum load in kilograms.
H — speed symbol, a letter mapping to a maximum sustained speed.

Light-truck sizes extend the sentence. LT265/70R17 121/118S E carries a dual load index — 121 for single-wheel fitment, 118 per tire when mounted as duals on one axle end — plus a load range letter (E) that encodes ply rating and inflation ceiling. Flotation sizes abandon the metric pattern entirely: 35x12.50R17 states overall diameter in inches, then section width in inches, then construction and rim. Three families, three grammars, one input field on your intake form.

Anyone who wants the customer-facing version of this decoding can read the sidewall markings walkthrough we keep for drivers; this article is the engineering companion to that page.

Three Families of Size, One Input Field

Before writing any code, pin down the three concrete syntaxes you must accept.

Metric (P-metric and Euro-metric). P215/60R16 94H, 215/60R16 94H, 215/60ZR16, 215/60R16 94H XL. The P prefix is optional and its absence changes load calculation standards (Euro-metric tires at the same size often carry slightly different maximum loads). XL or RF marks reinforced/extra-load casings.

LT-metric. LT265/70R17 121/118S E. Prefix mandatory, dual load index common, load range letter (C, D, E, F) frequently appended. These dominate the three-quarter-ton pickups that fill Calgary driveways, and they matter commercially because commercial tire work is disproportionately LT-metric.

Flotation. 35x12.50R17LT 121Q. Diameter-first, inches throughout, LT sometimes trailing the rim diameter rather than prefixing the string. The decimal in 12.50 is load-bearing syntax: 12.5 and 12.50 must normalize to the same value.

A grammar in EBNF-ish form:

size        := metric | lt_metric | flotation
metric      := [prefix] width "/" aspect construction rim [service_desc]
lt_metric   := "LT" width "/" aspect construction rim [dual_service] [load_range]
flotation   := diameter "x" fwidth construction rim ["LT"] [service_desc]
prefix      := "P" | "T" | "ST"
construction:= ["Z"] ("R" | "D" | "B")
service_desc:= load_index [ "/" load_index ] speed_symbol ["XL" | "RF"]

That sketch is already more honest than a regex, because it names the alternatives instead of burying them in (?:...)? groups.

Why the One-Regex Approach Collapses

The naive implementation looks like this, and versions of it exist in production at plenty of companies:

import re

NAIVE = re.compile(r"([A-Z]*)(\d{3})/(\d{2})R(\d{2})\s*(\d{2,3})([A-Z])")

Enumerate its failures against genuine intake strings (illustrative examples drawn from the kinds of input any tire retailer sees, not a statistical sample):

Optional everything. 215/60R16 with no service description is a valid size. The regex demands load index and speed symbol.
Dual load index. 121/118S breaks the single (\d{2,3}) group, and a greedy fix silently swallows the second index into the aspect of a mangled parse.
ZR markers. 245/40ZR18 97Y puts a Z before the R. Patterns anchored on a bare R either miss it or mis-split the aspect ratio.
Flotation. 35x12.50R17 shares almost no surface syntax with metric sizes. One regex covering both families becomes unreadable.
Human separators. Web forms deliver 215-60-16, 215 60 16, 215/60/16, 215/60-R16, and the gloriously ambiguous 2156016. A rigid pattern rejects all of them, and rejected input at intake means a person re-keys data, which is where transcription errors breed.
Case and whitespace. p215/60r16 from a phone keyboard, tabs from spreadsheet paste, trailing M+S or 3PMSF badges the customer helpfully included.
Three-digit aspect and two-digit width don't exist — but 82-series legacy sizes and rim diameters like 22.5 (heavy truck) do. Half-inch rim diameters destroy (\d{2}).

The failure mode that hurts most is not rejection — it is a confident wrong parse. LT265/70R17 121/118S parsed by a greedy single-index pattern can yield load index 121 and drop 118S on the floor, and the record now overstates nothing but silently loses the dual rating that a dually fitment decision needs. Wrong-but-plausible data is worse than an error, which is the core argument for a real tokenizer.

Lexing the Sidewall: Tokens Before Meaning

Treat the input the way a compiler treats source: normalize, tokenize, then parse. The tokenizer's only job is to slice the string into typed chunks without deciding what they mean.

import re
from dataclasses import dataclass
from typing import Iterator

@dataclass(frozen=True)
class Token:
    kind: str      # NUM, DEC, SEP, X, CONSTRUCT, WORD
    text: str
    pos: int

TOKEN_SPEC = [
    ("DEC",       r"\d{1,3}\.\d{1,2}"),          # 12.50, 22.5
    ("NUM",       r"\d{1,4}"),                    # 215, 60, 16, 94, 121
    ("X",         r"[xX×]"),                      # flotation separator
    ("CONSTRUCT", r"ZR|R|D|B(?![A-Z])"),          # construction markers
    ("SEP",       r"[/\-\s]+"),                   # slash, dash, spaces
    ("WORD",      r"[A-Z]{1,5}"),                 # P, LT, XL, S, E, TL...
]

MASTER = re.compile(
    "|".join(f"(?P<{k}>{p})" for k, p in TOKEN_SPEC), re.IGNORECASE
)

def tokenize(raw: str) -> Iterator[Token]:
    s = raw.strip().upper().replace("×", "X")
    for m in MASTER.finditer(s):
        kind = m.lastgroup
        if kind == "SEP":
            yield Token("SEP", "/", m.start())
        else:
            yield Token(kind, m.group(), m.start())

Two deliberate choices deserve comment. First, DEC outranks NUM in the alternation so 12.50 never fractures into 12, ., 50. Second, every separator collapses to a canonical /, which is how 215-60-16 and 215 60 16 stop being special cases before the parser ever sees them.

There is a subtlety in CONSTRUCT versus WORD: the letter R is both a construction marker and a possible fragment of a word token. Resolving that requires context, and context is the parser's job, not the lexer's. The lexer emits CONSTRUCT greedily and the parser is written to re-interpret when the grammar says a construction marker cannot appear at that position. This division of labour is exactly why the two-stage design stays maintainable while the one-regex design rots.

A Recursive-Descent Parser for Three Grammars

With tokens in hand, the parser is a small recursive-descent routine with one lookahead decision: does the stream look flotation-shaped (NUM/DEC, X, ...) or metric-shaped (WORD?, NUM, SEP, ...)?

from dataclasses import dataclass, field
from typing import Optional

@dataclass
class ParsedSize:
    family: str                       # "metric" | "lt_metric" | "flotation"
    prefix: Optional[str] = None      # P, LT, T, ST
    section_width_mm: Optional[float] = None
    aspect_ratio: Optional[float] = None
    overall_diameter_in: Optional[float] = None   # flotation only
    section_width_in: Optional[float] = None      # flotation only
    construction: str = "R"
    zr_marker: bool = False
    rim_diameter_in: float = 0.0
    load_index_single: Optional[int] = None
    load_index_dual: Optional[int] = None
    speed_symbol: Optional[str] = None
    load_range: Optional[str] = None  # C, D, E, F
    reinforced: bool = False          # XL / RF
    warnings: list = field(default_factory=list)

class SizeParseError(ValueError):
    pass

class SizeParser:
    def __init__(self, tokens):
        self.toks = [t for t in tokens if t.kind != "SEP" or True]
        self.i = 0

    def peek(self, k=0):
        j = self.i + k
        return self.toks[j] if j < len(self.toks) else None

    def take(self, kind=None):
        tok = self.peek()
        if tok is None or (kind and tok.kind != kind):
            want = kind or "any token"
            raise SizeParseError(f"expected {want} at position {self.i}")
        self.i += 1
        return tok

    def skip_seps(self):
        while self.peek() and self.peek().kind == "SEP":
            self.i += 1

    def parse(self) -> ParsedSize:
        self.skip_seps()
        if self.looks_flotation():
            return self.parse_flotation()
        return self.parse_metric_family()

    def looks_flotation(self) -> bool:
        a, b = self.peek(0), self.peek(1)
        return (
            a is not None and b is not None
            and a.kind in ("NUM", "DEC") and b.kind == "X"
        )

The metric branch shows how optional prefixes and dual indexes are handled without regex contortions:

    def parse_metric_family(self) -> ParsedSize:
        out = ParsedSize(family="metric")
        tok = self.peek()
        if tok and tok.kind == "WORD" and tok.text in ("P", "LT", "T", "ST"):
            out.prefix = self.take().text
            if out.prefix == "LT":
                out.family = "lt_metric"
        out.section_width_mm = float(self.take("NUM").text)
        self.skip_seps()
        out.aspect_ratio = float(self.take("NUM").text)
        self.skip_seps()
        c = self.peek()
        if c and c.kind == "CONSTRUCT":
            marker = self.take().text
            out.zr_marker = marker.startswith("Z")
            out.construction = marker[-1]
        else:
            out.warnings.append("construction marker missing; assumed R")
        rim = self.take()
        if rim.kind not in ("NUM", "DEC"):
            raise SizeParseError("rim diameter expected after construction")
        out.rim_diameter_in = float(rim.text)
        self.parse_service_description(out)
        return out

    def parse_service_description(self, out: ParsedSize) -> None:
        self.skip_seps()
        nxt = self.peek()
        if nxt and nxt.kind == "NUM":
            out.load_index_single = int(self.take().text)
            self.skip_seps()
            if self.peek() and self.peek().kind == "NUM":
                out.load_index_dual = int(self.take().text)
                self.skip_seps()
        while self.peek() and self.peek().kind in ("WORD", "CONSTRUCT"):
            word = self.take().text
            if word in ("XL", "RF"):
                out.reinforced = True
            elif word in ("C", "D", "E", "F") and out.family == "lt_metric":
                out.load_range = word
            elif len(word) <= 2 and out.speed_symbol is None:
                out.speed_symbol = word
            else:
                out.warnings.append(f"unrecognized suffix token: {word}")

Notice the re-interpretation trick: in service-description position, a CONSTRUCT token like a stray R (a speed symbol!) or D (a load range!) is consumed as a word. The lexer's greedy guess gets corrected by grammatical context. 245/40ZR18 sets zr_marker=True and construction="R", preserving the historical marker without letting it pollute the structural fields.

The flotation branch is short because its shape is rigid:

    def parse_flotation(self) -> ParsedSize:
        out = ParsedSize(family="flotation")
        out.overall_diameter_in = float(self.take().text)
        self.take("X")
        out.section_width_in = float(self.take().text)
        c = self.peek()
        if c and c.kind == "CONSTRUCT":
            out.construction = self.take().text[-1]
        out.rim_diameter_in = float(self.take().text)
        nxt = self.peek()
        if nxt and nxt.kind == "WORD" and nxt.text == "LT":
            out.prefix = self.take().text
        self.parse_service_description(out)
        return out

Wrap the pipeline in one function and every call site stays clean:

def parse_size(raw: str) -> ParsedSize:
    return SizeParser(list(tokenize(raw))).parse()

parse_size("P215/60R16 94H")          # metric, LI 94, speed H
parse_size("lt265/70r17 121/118S E") # lt_metric, dual LI, load range E
parse_size("35x12.50R17LT 121Q")      # flotation
parse_size("215 60 16")               # metric with warnings, no service desc

Run-Together Digits and the Ambiguity Budget

2156016 is the intake string that teaches humility. Seven digits, no separators, typed by someone reading their own sidewall in a parkade. A parser cannot split it purely syntactically — but it can generate candidates and score them against physical plausibility:

VALID_WIDTHS = set(range(125, 455, 10)) | {145, 155, 165}   # metric widths
VALID_ASPECTS = set(range(25, 90, 5)) | {82}
VALID_RIMS = {13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 24}

def split_run_together(digits: str):
    """Yield plausible (width, aspect, rim) splits of an unseparated digit run."""
    n = len(digits)
    for wi in (3,):
        for ai in (2,):
            ri_len = n - wi - ai
            if ri_len not in (2,):
                continue
            w, a, r = int(digits[:wi]), int(digits[wi:wi+ai]), int(digits[wi+ai:])
            if w in VALID_WIDTHS and a in VALID_ASPECTS and r in VALID_RIMS:
                yield (w, a, r)

list(split_run_together("2156016"))   # [(215, 60, 16)]

For seven digits the split is usually unique; six digits (2256016 minus a digit, say 225616) can be genuinely ambiguous, and the correct system behaviour is to refuse to guess silently. Return all candidates, force a human confirmation at intake, and record which candidate was chosen. The design principle: spend your ambiguity budget on asking one good question rather than on being wrong quietly. The same principle underlies the plain-language advice on our be-tire-smart explainer — when a marking is unclear, verify before acting on it.

The Normalized Fitment Model

Parsing produces a struct; a business needs entities. The model that has held up for us separates five concerns that tutorials usually mash into one table.

1. tire_size — the pure geometric designation, deduplicated. 215/60R16 is one row no matter how many products or vehicles reference it.

2. service_rating — load index (single and dual), speed symbol, load range, reinforced flag. Kept apart from size because one geometric size ships with many ratings: 215/60R16 exists as 94H, 95H XL, 99T winter, and conflating them is precisely how unsafe substitutions sneak into records.

3. vehicle_fitment — vehicle (year/make/model/trim) joined to an OE (original equipment) size-and-rating pair, with a flag for front/rear staggered setups.

4. fitment_option — approved alternatives per vehicle: plus-size and minus-size equivalents with computed diameter deviation. Minus-sizing shows up constantly in winter: many drivers run a smaller rim with a taller sidewall on their winter set for pothole resilience and narrower contact patch.

5. intake_record — the raw string as typed, the parse result, parser warnings, and the resolved tire_size id. Never discard the raw input; it is your regression-test corpus and your audit trail.

Schema Sketch in SQL

CREATE TABLE tire_size (
    id              INTEGER PRIMARY KEY,
    family          TEXT NOT NULL CHECK (family IN ('metric','lt_metric','flotation')),
    prefix          TEXT,
    section_width_mm REAL,
    aspect_ratio    REAL,
    diameter_in     REAL,          -- flotation overall diameter
    width_in        REAL,          -- flotation section width
    construction    TEXT NOT NULL DEFAULT 'R',
    rim_diameter_in REAL NOT NULL,
    canonical_text  TEXT NOT NULL UNIQUE
);

CREATE TABLE service_rating (
    id              INTEGER PRIMARY KEY,
    size_id         INTEGER NOT NULL REFERENCES tire_size(id),
    load_index      INTEGER,
    load_index_dual INTEGER,
    speed_symbol    TEXT,
    load_range      TEXT,
    reinforced      INTEGER NOT NULL DEFAULT 0,
    UNIQUE (size_id, load_index, load_index_dual, speed_symbol, load_range, reinforced)
);

CREATE TABLE vehicle_fitment (
    id              INTEGER PRIMARY KEY,
    vehicle_key     TEXT NOT NULL,          -- e.g. '2019|toyota|rav4|xle'
    axle            TEXT NOT NULL DEFAULT 'all',  -- 'all' | 'front' | 'rear'
    oe_rating_id    INTEGER NOT NULL REFERENCES service_rating(id)
);

CREATE TABLE fitment_option (
    id              INTEGER PRIMARY KEY,
    fitment_id      INTEGER NOT NULL REFERENCES vehicle_fitment(id),
    rating_id       INTEGER NOT NULL REFERENCES service_rating(id),
    kind            TEXT NOT NULL CHECK (kind IN ('oe','plus1','plus2','minus1','winter_alt')),
    diam_deviation_pct REAL NOT NULL
);

CREATE TABLE intake_record (
    id              INTEGER PRIMARY KEY,
    received_at     TEXT NOT NULL,
    raw_text        TEXT NOT NULL,
    channel         TEXT NOT NULL,          -- 'web_form','counter','phone','mobile_unit'
    parse_ok        INTEGER NOT NULL,
    parse_warnings  TEXT,
    resolved_rating_id INTEGER REFERENCES service_rating(id),
    resolved_by     TEXT                    -- 'auto' | 'staff_confirmed'
);

The canonical_text uniqueness constraint is the workhorse. Every parse serializes back to one canonical string, and the database — not application code — enforces that 215/60 R 16, 215-60-16, and P215/60R16 collapse toward the intended identity (prefix retained where it is semantically meaningful, since P-metric and Euro-metric load standards differ).

def canonical(p: ParsedSize) -> str:
    if p.family == "flotation":
        core = f"{p.overall_diameter_in:g}x{p.section_width_in:.2f}{p.construction}{p.rim_diameter_in:g}"
        core += p.prefix or ""
    else:
        pre = p.prefix or ""
        z = "Z" if p.zr_marker else ""
        core = f"{pre}{p.section_width_mm:g}/{p.aspect_ratio:g}{z}{p.construction}{p.rim_diameter_in:g}"
    svc = ""
    if p.load_index_single is not None:
        svc = f" {p.load_index_single}"
        if p.load_index_dual is not None:
            svc += f"/{p.load_index_dual}"
        if p.speed_symbol:
            svc += p.speed_symbol
    if p.load_range:
        svc += f" {p.load_range}"
    if p.reinforced:
        svc += " XL"
    return core + svc

Round-tripping — canonical(parse_size(canonical(parse_size(x)))) equals canonical(parse_size(x)) — is a property test worth wiring into CI on day one.

Overall Diameter: The Equivalence Math

Two sizes are interchangeable candidates only when their overall diameters land close together, because diameter drives speedometer accuracy, gearing, drivetrain stress on AWD systems, and body clearance. The formula for metric sizes:

sidewall_height_mm = section_width_mm × (aspect_ratio / 100)
overall_diameter_mm = rim_diameter_in × 25.4 + 2 × sidewall_height_mm

In code, with flotation handled in the same function:

def overall_diameter_mm(p: ParsedSize) -> float:
    if p.family == "flotation":
        return p.overall_diameter_in * 25.4
    sidewall = p.section_width_mm * (p.aspect_ratio / 100.0)
    return p.rim_diameter_in * 25.4 + 2.0 * sidewall

def deviation_pct(candidate: ParsedSize, reference: ParsedSize) -> float:
    ref = overall_diameter_mm(reference)
    return (overall_diameter_mm(candidate) - ref) / ref * 100.0

Worked example — a plus-one conversion, numbers shown in full so you can check the arithmetic:

Reference: 205/55R16
  sidewall = 205 × 0.55           = 112.75 mm
  diameter = 16 × 25.4 + 2×112.75 = 406.40 + 225.50 = 631.90 mm  (24.88 in)

Candidate: 225/45R17
  sidewall = 225 × 0.45           = 101.25 mm
  diameter = 17 × 25.4 + 2×101.25 = 431.80 + 202.50 = 634.30 mm  (24.97 in)

Deviation = (634.30 − 631.90) / 631.90 = +0.38 %   → excellent match

And a flotation-to-metric comparison, which the unified function makes one-line work:

35x12.50R17         → 35 × 25.4              = 889.00 mm
Nearest LT-metric: LT315/70R17
  sidewall = 315 × 0.70            = 220.50 mm
  diameter = 431.80 + 441.00       = 872.80 mm
Deviation = (872.80 − 889.00) / 889.00 = −1.82 %   → acceptable, flag for clearance

Revolutions per kilometre fall out of the same value and matter for odometer-sensitive fleet records:

import math

def revs_per_km(p: ParsedSize) -> float:
    return 1_000_000.0 / (math.pi * overall_diameter_mm(p))

# 205/55R16 → 1,000,000 / (π × 631.90) ≈ 503.8 rev/km

A practical threshold set, encoded as policy rather than folklore: deviation within ±1.5 % auto-approves as an equivalence candidate, ±1.5–3 % flags for human review with a clearance note, beyond ±3 % rejects. Those bands are a policy choice for our operation, not a universal standard — the point is that they live in one table, not scattered through if statements.

Load Index and Speed Symbol: Small Tables, Big Consequences

Load index is a lookup, not a formula. A slice of the standardized table:

LOAD_INDEX_KG = {
    88: 560, 89: 580, 90: 600, 91: 615, 92: 630, 93: 650,
    94: 670, 95: 690, 96: 710, 97: 730, 98: 750, 99: 775,
    100: 800, 104: 900, 110: 1060, 116: 1250, 118: 1320, 121: 1450,
}

SPEED_KMH = {
    "N": 140, "P": 150, "Q": 160, "R": 170, "S": 180, "T": 190,
    "U": 200, "H": 210, "V": 240, "W": 270, "Y": 300,
}

Two consequences follow. First, load index 94 means 670 kg per tire, so an OE spec of 94H on a crossover establishes a floor: a candidate rated 91 (615 kg) carries 55 kg less per corner than the manufacturer engineered for, and that difference compounds under a roof box, five passengers, and a Highway 2 grade. The plain-English version of this lives on our load index explainer; the systems version is a hard validation rule below. Second, speed symbols are ordered but not alphabetically — H sits between U and V for historical reasons — so comparisons must go through the table, never through ord().

Dual-index LT ratings add a wrinkle worth encoding: 121/118S means 1450 kg in single fitment but 1320 kg per tire when run as duals, because heat dissipation between paired tires is worse. If your model stores only the single figure, dually capacity math silently overstates by roughly 10 %.

Validation Rules That Refuse Dangerous Fitments

Validation is where the data model pays rent. Every quote line and every changeover record passes through a rule engine before a size is accepted against a vehicle:

from enum import Enum

class Severity(Enum):
    BLOCK = "block"
    REVIEW = "review"
    NOTE = "note"

def validate_fitment(candidate: ParsedSize, oe: ParsedSize, season: str) -> list:
    findings = []

    li_c, li_o = candidate.load_index_single, oe.load_index_single
    if li_c is not None and li_o is not None and li_c < li_o:
        findings.append((Severity.BLOCK,
            f"load index {li_c} below OE spec {li_o}: "
            f"{LOAD_INDEX_KG.get(li_c,'?')} kg vs {LOAD_INDEX_KG.get(li_o,'?')} kg"))

    sc, so = candidate.speed_symbol, oe.speed_symbol
    if sc in SPEED_KMH and so in SPEED_KMH and SPEED_KMH[sc] < SPEED_KMH[so]:
        sev = Severity.REVIEW if season == "winter" else Severity.BLOCK
        findings.append((sev,
            f"speed rating downgrade {so}→{sc} "
            f"({SPEED_KMH[so]}→{SPEED_KMH[sc]} km/h)"))

    dev = deviation_pct(candidate, oe)
    if abs(dev) > 3.0:
        findings.append((Severity.BLOCK, f"diameter deviation {dev:+.1f}% exceeds 3%"))
    elif abs(dev) > 1.5:
        findings.append((Severity.REVIEW, f"diameter deviation {dev:+.1f}%; check clearance"))

    if oe.family == "lt_metric" and candidate.family == "metric":
        findings.append((Severity.BLOCK,
            "P-metric candidate against LT OE spec; derate rules not satisfied"))

    return findings

The winter carve-out on speed downgrades reflects a widely accepted industry convention: dedicated winter tires are commonly permitted one step below the OE speed symbol because winter compounds rarely reach the highest ratings, and the trade is disclosed to the driver. Encoding it as REVIEW rather than auto-pass keeps a human in that disclosure loop. The LT-versus-P-metric rule guards the opposite direction: passenger-metric load figures cannot be compared one-to-one against light-truck specs without derating math, so the safe default is refusal.

What the engine deliberately does not do is silently "fix" anything. A blocked fitment produces a human-readable finding that a staff member resolves with the customer — usually by steering toward the correct spec on our guide to buying tires in Calgary terms: match or exceed OE load, respect the diameter envelope.

Fuzzy Matching the Typos People Actually Make

Real intake text contains a small, learnable set of corruption patterns (illustrative catalogue, not a frequency claim):

Character confusions: O↔0, l↔1, S↔5, B↔8.
Transpositions: 215/06R16 for 215/60R16.
Dropped construction letter: 215/6016.
Slash-for-R: 225/60/16.
Star-for-x in flotation: 35*12.5*17.
Unit smuggling: 215/60R16" with a stray inch mark.

A correction layer sits in front of the tokenizer and proposes, never imposes:

CONFUSIONS = str.maketrans({"O": "0", "o": "0", "l": "1", "I": "1", "*": "x"})

def prenormalize(raw: str) -> str:
    s = raw.translate(CONFUSIONS).strip().rstrip('"').upper()
    s = re.sub(r"(\d{3})/(\d{2})/(\d{2}(?:\.5)?)$", r"\1/\2R\3", s)  # slash-for-R
    return s

def levenshtein(a: str, b: str) -> int:
    if len(a) < len(b):
        a, b = b, a
    prev = list(range(len(b) + 1))
    for i, ca in enumerate(a, 1):
        cur = [i]
        for j, cb in enumerate(b, 1):
            cur.append(min(prev[j] + 1, cur[j-1] + 1, prev[j-1] + (ca != cb)))
        prev = cur
    return prev[-1]

def suggest(raw: str, catalog: list[str], max_dist: int = 2) -> list[str]:
    cleaned = prenormalize(raw)
    scored = sorted(
        ((levenshtein(cleaned, c), c) for c in catalog),
        key=lambda t: t[0],
    )
    return [c for d, c in scored if d <= max_dist][:3]

The catalog is not "all syntactically valid sizes" — it is the finite set of sizes that physically exist in the market plus everything previously confirmed in intake_record. That last part matters: aspect ratio 06 is syntactically fine and physically absurd, and a market catalog rejects it while pure grammar cannot. Suggestions above edit distance 2 are discarded because a wrong confident suggestion is the same disease as a wrong confident parse. When nothing scores, the record routes to staff, exactly like an ambiguous digit run.

Transposition detection earns a special case. Damerau-Levenshtein (which counts adjacent swaps as one edit) treats 215/06R16 → 215/60R16 as distance 1, and combined with the plausibility check — 06 is not a valid aspect ratio, 60 is — the system can rank that correction first with high confidence while still routing it through confirmation.

How a Small Operation Actually Uses This

Concrete flows, because architecture without usage is decoration.

Quote intake. A driver submits a size through the web form or the online request page. The string hits prenormalize → tokenize → parse → validate, and one of three things happens: a clean parse attaches a service_rating id to the quote; a parse-with-warnings shows staff the raw string beside the interpretation for one-click confirmation; a failed parse presents fuzzy suggestions. The measurable win is that staff review interpretations instead of re-keying strings, and every confirmation enriches the catalog.

Seasonal changeover records. Calgary compresses tire logistics into two brutal windows — the October scramble onto winter rubber and the April–May return to three-season sets, the annual rhythm described on our seasonal changeover page. During those weeks, the interesting data problem is that each customer has two recorded sets, and the model must answer: which set is on the vehicle, which is in the customer's garage, and do the two sets agree with the vehicle's OE envelope? Storing both as service_rating references against the same vehicle_fitment row makes the winter/summer diff a query, not a phone conversation. Minus-one winter setups are the norm here, so the fitment_option.kind = 'winter_alt' rows with their precomputed diameter deviations do real work every October.

Mixed-set detection. When a mobile unit records sizes wheel-by-wheel at a customer's driveway, four independent parses land per vehicle. A trivial GROUP BY catches the vehicle running 215/60R16 on three corners and 205/60R16 on the fourth — a mismatch the owner usually inherited from a roadside change and never noticed. Same parser, zero extra code, genuinely useful safety catch.

Fleet records. For fleet accounts, revs_per_km from the diameter function reconciles hub odometer readings across mixed LT-metric and flotation fitments, and dual-index handling stops dually capacity from being overstated. None of this requires the operation to be large; it requires the model to be honest.

Edge Cases From the Intake Pile

A grab bag of real-shaped inputs (again illustrative, anonymized to their structure) and how the pipeline handles each:

225/65R17 102H 102H — the customer pasted the rating twice. The parser reads the second 102 as a dual index, then a plausibility rule fires: dual index on a non-LT family is a warning, and equal single/dual values collapse to single with a note.
235/55R19 105V XL (front) 255/50R19 107V XL (rear) — a staggered fitment in one field. The tokenizer's leftover-token count tells the parser input remains after a complete parse; the pipeline re-enters and emits two records tagged front/rear from the parenthetical words.
205/55R16 91H M+S — M+S is an all-season mud-and-snow badge, not part of the size grammar. It lands in warnings and maps to a season attribute, which is exactly the metadata that distinguishes a three-season set on our all-season overview from a mountain-snowflake-rated one covered by the all-weather overview.
LT235/85R16 120/116Q LRE — LRE is "load range E" glued into one token. A tiny suffix rewrite (LR([C-F]) → \1) in prenormalization handles the whole family of glued load ranges.
31x10.5R15 versus 31x10.50R15 — decimal-width normalization; both canonicalize to 31x10.50R15.
275/65R18 en hiver — French annotations appear in Alberta intake more often than you'd guess. Unknown words fall into warnings and never corrupt structural fields; the parse succeeds.
225,60,16 — comma separators from European-formatted spreadsheets. One character class addition to SEP, plus a guard so commas inside digit groups (1,450 kg) don't split numbers.

Every one of these started life as a parser bug. The intake_record table is why they stopped being bugs: raw strings became regression fixtures the same day they were mis-handled.

Property Tests Beat Example Tests Here

Example-based tests freeze yesterday's bugs; property-based tests hunt tomorrow's. Three properties carry most of the weight:

from hypothesis import given, strategies as st

widths = st.sampled_from(sorted(VALID_WIDTHS))
aspects = st.sampled_from(sorted(VALID_ASPECTS))
rims = st.sampled_from(sorted(VALID_RIMS))

@given(widths, aspects, rims)
def test_roundtrip_is_stable(w, a, r):
    s = f"{w}/{a}R{r}"
    once = canonical(parse_size(s))
    twice = canonical(parse_size(once))
    assert once == twice

@given(widths, aspects, rims, st.sampled_from(["-", " ", "/", "  "]))
def test_separator_invariance(w, a, r, sep):
    messy = f"{w}{sep}{a}{sep}{r}"
    clean = f"{w}/{a}R{r}"
    assert canonical(parse_size(messy)) == canonical(parse_size(clean))

@given(widths, aspects, rims)
def test_diameter_positive_and_sane(w, a, r):
    p = parse_size(f"{w}/{a}R{r}")
    d = overall_diameter_mm(p)
    assert 450.0 < d < 1400.0   # physical envelope for road tires

The separator-invariance property alone caught more regressions than the entire example suite, because every tokenizer refactor risks quietly changing how junk whitespace is folded. A fourth suite fuzzes pure garbage — emoji, SQL fragments, 10 kB strings — asserting only that the parser raises SizeParseError cleanly rather than looping or mis-parsing. Hostile-input discipline is cheap insurance for anything wired to a public form.

Boundaries: What This Model Refuses to Know

A data model is defined by its exclusions as much as its entities, and ours excludes anything beyond tire and lubricant work, because that is the entire service surface at our storefront. There is no suspension geometry table, no brake-clearance calculator for oversized fitments, no steering-angle model — when a plus-two fitment raises clearance questions on lowered vehicles, the finding text tells the customer to verify with a mechanical specialist, full stop. Encoding your operational boundary into the schema keeps software from promising what the business doesn't perform, and it also keeps the model small enough that one developer can hold it in their head.

The parser itself has boundaries too. It does not attempt speed-symbol inference from ZR markers (a ZR with no explicit symbol stores speed_symbol=None plus a warning, because guessing Y versus W is a 30 km/h error). It does not auto-resolve P-metric versus Euro-metric load standards; it stores the prefix and lets the rating table carry the truth. And it never deletes a raw input string, ever.

Takeaways for Anyone Building One of These

Model the designation as a grammar with three families; the moment you write metric | lt_metric | flotation as branches, ZR markers and dual load indexes become local problems instead of regex-wide ones.
Lex first, parse second, and let grammatical context re-interpret ambiguous tokens like a service-position R.
Keep geometric size and service rating as separate entities; every dangerous substitution I've seen traces back to conflating them.
Make canonical text a database constraint and round-tripping a CI property.
Do the diameter math in one function that spans families, and put approval thresholds in data.
Validate with severities — block, review, note — and never silently repair safety-relevant fields.
Constrain fuzzy suggestions with a physical-market catalog and route low confidence to humans.
Hoard raw intake strings; they are the best test corpus your system will ever get for free.

The whole apparatus — lexer, parser, schema, validators, fuzzers — is maybe twelve hundred lines. Small enough for a tire-and-oil operation in Calgary, rigorous enough that a mis-typed aspect ratio gets caught before it becomes a wrong set of tires on a real vehicle driving down Deerfoot in January. That trade is the entire reason to treat a sidewall string as a language instead of a product code.

Designing a Tire-Wear Image Evidence Pipeline: Capture Protocols, Metadata Schemas, Quality Scoring, and Audit Trails

KMJ Tire Calgary — Tue, 04 Aug 2026 16:10:50 +0000

Designing a Tire-Wear Image Evidence Pipeline: Capture Protocols, Metadata Schemas, Quality Scoring, and Audit Trails

Photographs of tire wear often enter an operations system as informal attachments: a few phone images, a vehicle identifier, and perhaps a short note. That is enough for a human who was present, but it is weak evidence for someone reviewing the record weeks later. The image may be sharp yet show the wrong wheel. A useful close-up may have lost its relationship to the vehicle overview. Compression may erase small cracks. A file timestamp may describe an export rather than capture. If a computer-vision project later consumes that archive, hidden inconsistency becomes labelled-data debt.

This article designs a photographic evidence pipeline rather than a tread-depth measurement system. Its job is to establish what was photographed, when and how it was captured, whether the pixels are usable, who changed each interpretation, and which facts remain uncertain. The design deliberately keeps image observations separate from service decisions. KMJ Tire performs tire services and oil changes; a photograph suggesting a non-tire mechanical concern should be documented and referred to an appropriate mechanical provider rather than represented as work KMJ performs.

Calgary makes this problem interesting. Chinook-driven thaw and refreeze cycles change what is visible on a tire. Road salt leaves pale films. Gravel season adds dust and small stones. A vehicle arriving from Deerfoot Trail may carry wet spray, while one returning from Highway 1 west can arrive with packed snow or mountain-road grime. An evidence pipeline must record these conditions instead of pretending every image came from a clean laboratory.

Start With an Evidence Contract, Not a Camera App

The first engineering artifact should be a short evidence contract. It states what the pipeline can prove and what it cannot. A defensible contract might promise that every accepted image is attached to one inspection session, retains the original bytes, records capture context, receives automated quality measurements, and preserves reviewer actions. It should not promise that a photo alone determines tire safety, proves a root cause, or substitutes for an in-person assessment.

Model the session as the unit of work. A session belongs to a vehicle or fleet asset, but the identifier should be internal and minimally revealing. Within it, create wheel-position records, capture attempts, accepted originals, derived assets, automated checks, observations, and review events. That hierarchy prevents the familiar folder problem in which IMG_4832.jpg sits beside a note saying “rear tire” with no reliable indication of which rear position was intended.

The capture protocol needs required views. An operational baseline can include a vehicle-context frame, one wheel-context frame for each inspected position, a straight-on tread overview, and focused detail frames for notable areas. The protocol should allow extra images without treating quantity as quality. Ten nearly identical blurry frames are worse than four deliberate views with clear relationships.

Document exclusions too. Faces, house numbers, unrelated license plates, papers on a seat, and personal items have no evidentiary value for tire wear. The interface should help the operator avoid them before capture. Redaction is a fallback, not a reason to collect broadly. For driver education about tire condition, Be Tire Smart supplies useful background without turning an image record into a diagnosis.

Acceptance is a state transition, not a feeling. A frame can be captured, uploaded, validated, needs_recapture, accepted, redacted, superseded, or rejected. Only accepted originals and approved derivatives should reach review datasets. Raw attempts can have a shorter retention policy, provided the policy is explicit and legal requirements are respected.

Give Every Capture a Stable Identity

Never use a filename as the primary key. Mobile operating systems reuse names, messaging apps rewrite names, and exports reorder sequences. Generate a cryptographically random capture ID before the shutter action if the client permits it, then include that ID in the upload envelope. The server separately computes a content digest from the received bytes. Identity answers “which record?” while the digest answers “are these exact bytes already known?”

A useful naming convention is only a convenience:

{session_id}_{position}_{view_role}_{capture_id}.{ext}
01J4..._LR_TREAD_OVERVIEW_01J5....jpg

Do not embed customer names, phone numbers, addresses, or full vehicle identification numbers in object keys. Object-storage paths leak into logs, caches, support screenshots, and access reports. A random tenant-scoped prefix plus opaque IDs provides enough organization. Human-readable labels belong in authorized application views.

Capture identity also needs lineage. The original is immutable. Rotation, colour normalization, redaction, thumbnails, and annotation overlays are derivatives with their own digests and parent references. A reviewer must always be able to reach the untouched original, subject to access controls, and see which transformation produced the displayed asset.

The digest should be computed server-side using SHA-256 or a similarly appropriate contemporary algorithm. A client digest can accelerate resumable upload checks, but it is an assertion until the server verifies it. Store byte length, detected media type, decoder result, dimensions, colour profile, and digest in the same ingestion transaction. Reject polyglot or malformed files rather than trusting the extension.

Idempotency matters on weak connections. A phone moving between a service bay network and mobile data may repeat a request. An idempotency key scoped to the session and capture ID lets the server return the existing record instead of creating twins. Exact-byte duplicate detection should warn about repeated content while still preserving the attempted relationship for audit purposes.

Define a Calgary-Ready Capture Protocol

An effective protocol guides behaviour in seconds. Begin with a context frame showing enough of the vehicle and wheel location to establish position without collecting unrelated surroundings. Then move to the wheel context, tread overview, and any detail. The app should display a silhouette with LF, RF, LR, and RR positions; trailers and dual-wheel assets need an extensible position vocabulary rather than four hard-coded buttons.

Lighting instructions must respond to reality. Direct sun can make tread valleys black while washing out raised rubber. Indoor LEDs can flicker or create bands. Snow glare shifts exposure. A chinook afternoon can place one side of a vehicle in bright sun and the other in deep shade. The protocol should ask the operator to seek diffuse light, avoid flash reflections on wet rubber, and move the light source rather than digitally brightening a failed frame.

Surface condition deserves a required field with controlled values such as dry_clean, wet, salt_film, dust, snow, ice, mud, and unknown. Multiple values may apply. These are not cosmetic notes: they influence quality scoring and later model training. A network trained mainly on cleaned tires may fail on the slushy conditions common after a Calgary temperature swing.

Angle guidance should be role-specific. A tread overview needs the optical axis close to perpendicular to the local tread surface. A sidewall record needs lettering in focus and a frame broad enough to retain context; tire sidewall information helps operators understand which markings matter. Damage-detail frames can be oblique when the angle reveals depth, but they should follow a perpendicular establishing frame.

Highway context belongs in session metadata, not inferred from wear. An operator may record that an asset normally runs Deerfoot, Stoney Trail, urban deliveries, gravel approaches, or Highway 1 west when that fact is supplied by the fleet. The pipeline must not manufacture route history from pixels. Likewise, load context should reference verified operational data. Load-index guidance explains the marking, but an image of the marking does not prove the vehicle’s actual carried load.

Use a Metadata Schema That Admits Uncertainty

Metadata should distinguish observed, supplied, measured, inferred, and unknown values. Without provenance at the field level, a reviewer cannot tell whether wheel_position: LR came from the operator’s selection, a barcode association, or a vision model guess. Every material fact should carry a source and, where applicable, confidence.

Here is a compact upload envelope:

{
  "schema_version": "1.2",
  "session_id": "01J4Z8Q7KRF0Y2M5N8D3",
  "capture_id": "01J4Z9A2XQJ7C6H1P4TT",
  "asset_ref": "fleet_asset_8f42",
  "wheel_position": {"value": "LR", "source": "operator"},
  "view_role": "tread_overview",
  "captured_at": "2026-08-04T15:42:18.221Z",
  "timezone_offset_minutes": -360,
  "surface_conditions": ["wet", "salt_film"],
  "environment": {"location_class": "service_bay", "temperature_c": 7.0},
  "device": {"app_build": "2026.08.1", "camera_facing": "rear"},
  "operator_note": "Spray remained after Deerfoot arrival",
  "consent_basis": "fleet_service_record"
}

Treat device-generated EXIF as untrusted input. Preserve it in a quarantined metadata document, then normalize selected fields after validation. GPS should be removed unless it has a documented operational need. Device serial numbers and owner names should not enter analytics tables. Capture time can be compared with server receipt time, but clock drift means disagreement should create a flag rather than silently rewrite history.

Schema evolution must be intentional. Store a version on every envelope and write deterministic migrators. Never reinterpret an old enum in place. If wet later splits into standing_water and surface_damp, old records remain wet unless a human or reproducible process adds a new derived classification. That discipline is essential when image corpora outlive application releases.

Separate Transactional Records From Binary Objects

Large image bytes belong in object storage; relational records belong in a database. The database should retain the object key, version ID where supported, byte digest, size, media characteristics, ownership boundary, and retention class. A signed URL is a temporary access mechanism, never the stored identity of an image.

One PostgreSQL sketch looks like this:

create table evidence_image (
  image_id uuid primary key,
  session_id uuid not null references inspection_session(session_id),
  capture_id uuid not null,
  wheel_position text not null,
  view_role text not null,
  object_key text not null unique,
  object_version text,
  sha256 char(64) not null,
  byte_length bigint not null check (byte_length > 0),
  width_px integer not null,
  height_px integer not null,
  captured_at timestamptz,
  received_at timestamptz not null default now(),
  evidence_state text not null,
  schema_version text not null,
  metadata jsonb not null,
  unique (session_id, capture_id)
);

create index evidence_by_session_position
  on evidence_image(session_id, wheel_position, view_role);

The database transaction can reserve an image record before upload, but it should not mark the record accepted until object verification completes. A reconciliation worker finds abandoned reservations and orphaned objects. Use an outbox table to publish image.verified events only after the state change commits; this avoids a message announcing data that the database later rolls back.

Object policies should prevent overwriting an original key. If storage supports versioning and retention locks, configure them according to policy rather than relying only on application promises. Encryption at rest, tenant-scoped authorization, narrow service roles, and access logging are baseline controls. Backups need restore tests that reconnect database records with matching object versions.

Validate Pixels Before Asking a Human to Interpret Them

Ingestion validation should be fast, deterministic, and explainable. First decode the entire image, not merely its header. Enforce permitted formats, dimensions, pixel count, and file-size bounds. Normalize orientation for display as a derivative while retaining the original bytes and EXIF orientation. Reject decompression bombs and files whose detected content disagrees with their declared type.

Then calculate technical signals: Laplacian variance or another focus proxy, motion-blur directionality, clipped-shadow ratio, clipped-highlight ratio, local contrast, colour cast, glare area, obstruction estimate, and subject occupancy. None is universally meaningful by itself. Wet black rubber naturally produces highlights, while deep tread valleys naturally contain shadows. Thresholds need calibration by view role and surface condition.

Angle validation can use a lightweight segmentation model or geometric cues. For a tread overview, estimate the visible tread region, its principal axis, and perspective convergence. The system need not claim an exact camera angle. It can classify acceptable, borderline, or recapture with reasons such as “tread occupies too little of frame” or “perspective hides shoulder region.” A transparent reason is more useful than a mysterious score of 0.61.

Run these checks before upload completion when possible, but repeat them server-side. Client validation provides immediate coaching; server validation provides consistency and cannot be bypassed by an old app. Keep algorithm versions beside outputs so a later calibration does not rewrite history.

Build a Quality Score Without Hiding Failure Reasons

A composite score is convenient for queues, yet it should never replace component values. Suppose focus, exposure, framing, angle, and obstruction each range from zero to one. A weighted sum may be appropriate for ranking:

Q = 0.28F + 0.18E + 0.22R + 0.22A + 0.10O

Here O means visibility after accounting for obstruction, not the obstruction amount. The numbers are illustrative calibration weights, not safety thresholds. A hard rule sits alongside the sum: if subject occupancy is below the minimum for the selected view, the frame requires recapture regardless of Q. This prevents excellent lighting from compensating for a tire that occupies a tiny corner.

Store raw metrics, normalized components, calibration version, decision, and human-readable reasons. A result might say needs_recapture because focus is below the tread-overview threshold and the centre grooves are clipped. Avoid claims such as “bad tire.” The automated system is judging photographic fitness, not tire fitness.

Quality drift needs monitoring. Track distributions by device family, app version, bay, capture role, surface condition, and time of day. If a release suddenly raises shadow clipping, perhaps orientation or colour conversion changed. If one bay produces glare failures, the operational fix may be moving a lamp. Aggregate metrics should not become employee surveillance; define access and use boundaries before collection.

When a frame documents a potential puncture area, route the person to a tire-service assessment rather than issuing a pixel-based verdict. KMJ’s tire repair information provides service context, while the evidence record preserves what was visible at capture.

Detect Blur, Glare, Lighting, and Framing Carefully

Blur detection is frequently oversimplified. Laplacian variance drops for defocused images, but it also drops on smooth sidewall regions. Compute it over the detected tread or lettering region, not the whole frame. Add edge orientation analysis to distinguish directional motion blur from soft focus. Compare multiple scales so aggressive phone sharpening does not fool the metric.

Exposure validation should examine spatial maps. A global histogram can look healthy while the tread is nearly black and the concrete floor is bright. Segment the tire region first, then calculate clipped pixels and usable tonal range inside it. For wet tires, specular highlights can be acceptable when they do not obscure the feature of interest. Large continuous glare masks are more concerning than scattered points.

Framing uses the declared role. A wheel-context frame should include the full wheel and enough vehicle structure to support position. A tread-detail frame should fill more of the image but must not lose all orientation cues. The pipeline can request a paired overview rather than rejecting a valuable close-up solely for lacking context.

Lighting colour matters less than visibility, but extreme casts can harm later CV work. Preserve the original, estimate white balance only as a metric, and create a normalized derivative if the use case justifies it. Never replace the original with a cosmetically improved file. Road salt may resemble cracking or residue to a naive model; condition metadata and diverse training examples are the defence.

Treat Privacy and Redaction as Data Engineering

Privacy begins with minimization. Configure the capture UI so operators aim tightly, and explain why a wider neighbourhood scene is unnecessary. If the vehicle-context view includes a license plate, decide whether the operational record truly requires it. Often an internal asset reference already establishes identity, making visible plate text redundant.

Automated detectors can flag faces, plates, documents, QR codes, and screen content. Their output should create a privacy-review task, not silently destroy pixels. Redaction produces a derivative with a mask manifest describing detector version, reviewer, regions, method, and parent digest. Access to the original is narrower than access to the redacted working asset.

{
  "derivative_type": "privacy_redacted",
  "parent_sha256": "6a8d...e21c",
  "transform_version": "redact-2.3.0",
  "regions": [
    {"kind": "plate", "box": [122, 88, 284, 143], "method": "solid_fill"}
  ],
  "review_state": "approved",
  "reviewer_role": "privacy_reviewer"
}

Do not put sensitive content into free-text logs. Operator notes require length limits, clear guidance, and restricted visibility. Structured route classes are preferable to precise trip narratives. Retention should differ among originals, operational derivatives, temporary uploads, audit events, and model-training exports. A legal or contractual hold must override routine deletion through an explicit workflow.

Training exports deserve special scrutiny. Consent to maintain a fleet record does not automatically imply permission to train models. Build a dataset eligibility view that considers consent basis, retention, redaction, tenant policy, review status, and exclusions. Export manifests should list immutable digests so researchers cannot quietly substitute files.

Preserve an Append-Only Audit Story

Auditability does not require a fashionable ledger. It requires immutable source objects, append-only events, controlled corrections, reliable clocks, and verifiable relationships. A reviewer changing wheel position from LR to RR should create a correction event containing the old value, new value, reason, actor, time, and referenced image digest. The current projection can show RR, while history remains visible.

Create a hash chain within each session if tamper evidence is important. Each event includes the previous event hash, canonical payload hash, timestamp, and signer identity. Periodically anchor batch roots in a separately controlled system. This does not prove the original observation was true; it helps reveal later alteration.

event_hash = SHA256(
  canonical_json(payload) || previous_event_hash || actor_id || occurred_at
)

Canonicalization rules must be fixed and tested. JSON key order, Unicode normalization, decimal representation, and timestamp precision can otherwise change hashes without changing meaning. Key rotation and service-account identity also belong in the design. “System” is not a useful actor if five workers share it.

Audit logs must record reads of sensitive originals as well as writes. Alerts can flag bulk access, unusual export volume, or access outside a role’s normal scope. Keep operational monitoring separate from evidence interpretation: a download anomaly is a security concern, not information about tire condition.

Design Human Review Around Disagreement

The review interface should present context, not just a gallery. Show vehicle asset reference, wheel map, image role, surface conditions, original-versus-derivative status, quality reasons, and linked views. Let reviewers zoom into original resolution without forcing a lossy screenshot workflow. A side-by-side view is valuable when checking a redaction or comparing paired angles.

Use structured observations such as visible_irregularity, possible_foreign_object, sidewall_marking_legible, area_obscured, and no_observation_due_to_quality. These labels describe pixels. They should not be phrased as conclusive causes or service promises. A human can add a note explaining why in-person inspection is needed.

Disagreement is training data. If two reviewers differ, preserve both labels and route the item to adjudication. Do not overwrite the first interpretation. Measure agreement by label and condition; low agreement may reveal an ambiguous rubric rather than careless people. Gravel, salt residue, shadow, and water can each create systematic confusion.

Mechanical concerns outside tire service must be handled plainly. If the visible evidence raises a concern that would require alignment, brake, suspension, steering, diagnostic, or other mechanical work, the record should recommend assessment by an appropriate mechanical provider. It must not imply that KMJ offers that work. Wheel-balance symptoms are within tire-service context, and wheel balancing guidance can support a separate, properly scoped service discussion.

Prepare for Computer Vision Without Polluting Ground Truth

Computer-vision readiness begins with dataset governance, not model selection. Define the prediction target, unit of analysis, exclusion criteria, and label provenance. Split datasets by vehicle or fleet asset, not random images, or nearly identical views from one session can leak across training and test sets. Consider temporal splits to test whether a model survives new devices, seasons, and road residue.

Store annotations in an open, versioned representation. Bounding boxes may be adequate for foreign-object candidates; segmentation masks may be necessary for tread-region visibility or privacy regions. Each annotation references an image digest, ontology version, annotator role, and adjudication state. Model-generated prelabels must remain distinguishable from human labels.

Balance includes environments, not just classes. Seek coverage across dry summer rubber, wet shoulder-season conditions, winter snow residue, gravel dust, salt film, indoor bays, outdoor shade, and different phone cameras. Calgary’s seasons can create shortcuts: if every positive example comes from winter, a model may learn snow texture instead of the intended feature.

Do not normalize away operational reality. Keep originals and produce reproducible training transforms. Record resize method, crop, colour conversion, augmentation seed, and code version in an experiment manifest. A model card should state which capture roles and conditions were evaluated, known failure modes, and that photographic classification does not replace physical tire assessment.

For seasonal operational context, seasonal tire changes, all-weather tire guidance, and winter tire information can inform user education. Those pages are references, not labels for an image dataset.

Operate the Pipeline With Queues and Service-Level Signals

An ingestion pipeline should expose state counts and age, not merely request latency. Useful signals include uploads awaiting verification, images stuck in decoding, recapture requests without a replacement, privacy flags awaiting review, accepted sessions missing a required view, and derivatives whose parent cannot be resolved. Alert on backlog age and error-rate changes rather than every single expected rejection.

Use dead-letter handling with replay controls. A malformed image is a terminal validation result, while a transient object-store timeout is retryable. Classify errors explicitly so exponential backoff does not repeatedly decode malicious or impossible input. Replay must be idempotent and should retain the original algorithm version unless a deliberate reprocessing job is launched.

Capacity planning should use pixel volume and derivative work, not image count alone. A panoramic frame can cost far more than a normal phone image. Place upper bounds before decode, stream uploads, and isolate expensive CV tasks from the transactional API. Backpressure should coach the client to pause without losing capture identities.

Observability also needs trace boundaries. Propagate a session-safe trace ID through reservation, upload, verification, quality analysis, redaction, and review events. Do not place personal or vehicle-sensitive fields into metric labels. High-cardinality identifiers belong in secured logs or traces with appropriate retention, not in public dashboards.

Fleet operators can use commercial tire service information and fleet management context to understand the human service workflow around evidence. The pipeline itself should remain tenant-aware, policy-driven, and explicit about who can view which fleet records.

Walk Through a Calgary Fleet Capture

Consider a delivery asset returning from Stoney Trail after a cold morning followed by a warm chinook afternoon. The operator starts session S-204, selects the left-rear position, and records wet plus salt_film. A wheel-context image passes framing but contains a distant plate from another vehicle. The privacy detector flags it. The tread overview is sharp, although glare covers one shoulder. A focused second angle makes that shoulder visible.

The server verifies all three byte digests and retains originals. Quality analysis accepts the context frame for evidentiary linkage, requests redaction for general review use, marks the first tread frame borderline, and accepts the paired angle. The workflow does not average the two tread frames into a fictional certainty. It records that one region was obscured in one view and visible in another.

A reviewer notices a visible irregular area and labels its location without declaring a cause. The record routes the asset for an in-person tire assessment. If a separate observation suggests a non-tire mechanical issue, the note directs the fleet to an appropriate mechanical provider. Each action becomes an audit event.

Weeks later, a dataset curator queries only privacy-approved, accepted tread views with adjudicated labels and compatible consent. The export manifest pins digests and excludes the borderline frame. A researcher can reproduce the selection without seeing fleet names. That is what CV readiness looks like: careful operational provenance before clever modelling.

Test Failure Modes, Not Just Happy Paths

Automated tests should submit truncated JPEGs, misleading extensions, oversized dimensions, duplicated bytes under new names, rotated EXIF, missing timestamps, future timestamps, repeated idempotency keys, and invalid wheel positions. Verify that originals cannot be overwritten and that derivatives cannot point to nonexistent parents. Property-based tests are particularly useful for schema migrators and canonical event hashing.

Run visual test fixtures for glare, motion blur, defocus, shadow clipping, snow obstruction, salt film, and perspective. Threshold tests need boundary cases on both sides. Maintain device-specific fixtures when camera processing changes. A quality model that passes curated examples but fails after a phone update is not production-ready.

Exercise privacy failures: a detector misses a small face, a reviewer rejects an incomplete mask, an export attempts to include an unapproved original, and a deletion request intersects a retention hold. Confirm least-privilege roles by attempting forbidden reads. Restore an archived session from backup and recalculate digests.

Chaos tests can interrupt upload finalization between object write and database commit. Reconciliation should either reconnect a verified object to its reservation or quarantine it. Event consumers must tolerate duplicates and out-of-order delivery. A projection can be rebuilt from the append-only stream and compared with the live state.

Use a Deployment Checklist With Explicit Owners

Before rollout, assign owners for capture protocol, schema, storage policy, privacy review, quality calibration, security response, dataset governance, and user support. Write a data-flow diagram showing trust boundaries. Complete a privacy impact assessment appropriate to the organization. Document deletion, hold, export, correction, and breach-response procedures.

Pilot across different Calgary conditions and device families. Sample failures manually instead of watching only averages. Ask operators whether the guidance is understandable while their hands are cold or wet. Measure recapture burden by reason. Revise thresholds when evidence supports it, and version every revision.

A compact release checklist is:

original bytes are immutable and digest-verified;
required views and wheel positions are enforced;
privacy collection is minimized and redaction is reviewable;
quality components and reasons remain visible;
uncertain observations are labelled as uncertain;
non-tire mechanical concerns are referred elsewhere;
audit events survive corrections and reprocessing;
dataset exports require policy eligibility;
restore, replay, and deletion workflows have been tested;
dashboards reveal backlog age without exposing personal data.

Drivers seeking local service-area context can review KMJ Tire’s service areas. That operational reference should remain separate from technical evidence: geography may explain capture conditions, but it must not become a proxy label for tire condition.

Keep the Evidence Honest From Shutter to Archive

Model Recapture as a First-Class Operational Loop

Recapture should not be a generic rejection banner. It is a linked workflow connecting the failed attempt, the reason, the replacement, and the final disposition. A request needs a reason code such as focus_tread_region, missing_position_context, glare_obscures_subject, incorrect_view_role, or privacy_avoidance. Pair that code with one short instruction written for the operator: move closer, steady the device, step out of direct reflection, or add a context view. Avoid vague advice such as “take a better photo.”

The replacement carries a supersedes_capture_id relationship but does not erase the first attempt. This link enables useful analysis: which prompts solve failures, which reasons recur by device, and where the protocol itself causes confusion. Keep failed pixels out of normal reviewer screens after replacement unless an authorized audit view is opened. Operational visibility and clutter control can coexist.

Set loop limits deliberately. An app that demands six retries in blowing snow may encourage unsafe behaviour or fabricated compliance. After a small number of failed attempts, allow an exception state with a structured reason such as environmental obstruction, accessibility constraint, or device malfunction. A supervisor can decide whether another capture setting is appropriate. The exception is evidence about process limitations, not permission to mark the missing view as successful.

Offline capture adds another wrinkle. Validate locally with the bundled algorithm version, queue encrypted files, and display upload state clearly. Once connectivity returns, the server repeats validation and may disagree because its calibration is newer. Preserve both results. If server policy requires another frame, explain that the original passed an older on-device check. Silent contradictions destroy operator trust.

Measure recapture yield rather than rejection alone. If an instruction frequently produces an accepted replacement, it is useful. If “angle too steep” leads to another angle failure, improve the on-screen overlay or examples. Break results down by view role and environment, while maintaining fair-use limits around worker analytics. The objective is better evidence design, not a leaderboard of people working in different conditions.

Govern Reprocessing and Algorithm Change

Quality algorithms, privacy detectors, and CV models will evolve. Reprocessing should create new assessment records tied to the same immutable original, never update old outputs in place. Each assessment includes algorithm name, model digest, configuration digest, runtime environment, start time, completion time, and status. The application chooses which version is current through policy, while an auditor can compare generations.

A reprocessing plan should answer why the run exists. Perhaps a glare detector was recalibrated for wet winter tires, a privacy model gained better plate recognition, or a decoder vulnerability required fresh validation. Define the eligible population with a saved query and manifest before execution. Record counts selected, skipped, succeeded, and quarantined. A resumable job cursor prevents a partial run from producing an unknowable corpus.

Do not automatically promote every new score. Run shadow evaluation on representative Calgary conditions, compare false recapture and missed-obstruction rates, and inspect disagreements. A detector that improves on clean indoor images but worsens on salt film may not be ready for winter operations. Promotion needs an approval event referencing evaluation artifacts.

Rollback means switching policy to a prior approved assessment version; it does not mean deleting the new results. Downstream exports pin versions so a model-training experiment remains reproducible after production policy changes. Cache keys must include algorithm and transform versions, otherwise a thumbnail or score generated under one policy can masquerade as another.

Finally, budget reprocessing like any batch system. Bound concurrency, isolate queues from live ingestion, watch object-read costs, and pause when customer-facing capture latency rises. Security patches may justify priority, but routine experimentation should never destabilize the active evidence path. Operational discipline protects both the archive and the people depending on it.

A trustworthy tire-wear image pipeline is less about a sophisticated classifier than disciplined boundaries. The camera client establishes intent. The ingestion layer preserves exact bytes. Metadata admits its sources and uncertainty. Quality checks judge whether pixels are usable, not whether a tire is safe. Privacy controls minimize and redact unrelated information. Human review preserves disagreement. Immutable lineage makes later transformation visible.

These choices turn a pile of phone photos into an evidence system that can support operations today and carefully governed computer vision later. They also make failure useful. A blurred frame becomes a specific recapture reason. A salt-covered surface becomes documented context. A corrected wheel position becomes an auditable event. A model’s weak performance in snow becomes a known coverage gap rather than a surprise.

For Calgary fleets, the practical goal is not laboratory perfection. It is repeatable capture across chinooks, road spray, gravel, deep cold, and dramatic day-night temperature swings while retaining enough context for a competent person to review the record. Keep service decisions with qualified people, keep mechanical referrals within their proper scope, and let the pipeline do what software does well: preserve identity, enforce process, expose uncertainty, and make every transformation traceable.