DEV Community: Matt

Simulating an ice age on a public schedule across a real map

Matt — Mon, 02 Nov 2026 14:40:29 +0000

I make Last Thaw, a free browser strategy game. Up to a hundred players start with five settlers on a real map of Earth, cut into 408 regions, and have 30 real days to build an empire while an ice age advances from both poles. It's in early access and I'm looking for people to test it.

The ice is the clock of the whole game. It is also the one system every player feels whether they log in or not, so it had to be boring in the right ways: predictable, fair, and impossible to argue with. This post is how it works, from one table of numbers down to the transaction that freezes a region, and the parts I got wrong first.

Rule one: the schedule is public

I wanted the ice to be something you plan around, not something that ambushes you. So the schedule is not random, and it is not hidden. It is a list of points in the shared balance config, and the same list drives the server, the map overlay and the player-facing how to play page:

ice: {
  /** Production multiplier left when the ice line reaches a region's centre. */
  taperFloor: 0.25,
  /** Absolute latitude of the ice edge by match day; interpolated between points. */
  schedule: [
    { day: 0, latitude: 72 },
    { day: 7, latitude: 62 },
    { day: 14, latitude: 52 },
    { day: 21, latitude: 42 },
    { day: 28, latitude: 32 },
    { day: 30, latitude: 28 },
  ],
},

The line is an absolute latitude, so one number covers both hemispheres: on day 14 everything beyond 52 degrees north and 52 degrees south is under the ice. Ten degrees a week for four weeks, then a slower last stretch. By the end the survivors are crowded into the band around the equator, which is where the fighting gets interesting.

Turning that into a latitude for any moment is plain linear interpolation:

export function iceLatitudeOnDay(day: number): number {
  const s = balance.ice.schedule;
  if (day <= s[0]!.day) return s[0]!.latitude;
  for (let i = 1; i < s.length; i++) {
    const a = s[i - 1]!;
    const b = s[i]!;
    if (day <= b.day) {
      const t = (day - a.day) / (b.day - a.day);
      return a.latitude + (b.latitude - a.latitude) * t;
    }
  }
  return s[s.length - 1]!.latitude;
}

Because it is a pure function in a shared package, the browser can call it too. The map's "Ice forecast" overlay asks the same function which day each region freezes, so what you see is exactly what the server will do. There is no second implementation to drift.

The inverse is just as useful: "on which day does this latitude freeze?" I loop over days rather than inverting the piecewise function, because a match is 30 days long and a loop of 30 is not worth being clever about:

export function freezeDayForLatitude(absLat: number): number | null {
  for (let day = 1; day <= balance.match.lengthDays; day++) {
    if (absLat >= iceLatitudeOnDay(day)) return day;
  }
  return null;
}

null means "never": the tropics survive the month.

Regions are not points

My first version froze a region when the line passed its centre. It was simple and, once I played against it, it felt awful. A big region like a slice of Canada or Siberia would produce at full rate right up to the moment it vanished, and then everything in it was gone in one step. Players had no signal that they should be leaving.

Regions in Last Thaw are generated from real borders (I wrote about that in the first post in this series), so each one knows its centre and how far it reaches north and south. That gave me a better rule: the ice touches a region when the line reaches its pole-facing tip, production tapers as the line moves from the tip to the centre, and the region freezes when the line passes the centre.

export function iceExposure(r: IceShape, day: number) {
  const line = iceLatitudeOnDay(day);
  const centre = Math.abs(r.lat);
  const tip = Math.max(centre, poleTipLatitude(r));
  if (centre >= line) return { frozen: true, factor: 0, touched: true };
  if (tip < line || tip <= centre) return { frozen: false, factor: 1, touched: false };
  const t = (tip - line) / (tip - centre); // 0 at the tip, 1 at the centre
  const factor = 1 - (1 - balance.ice.taperFloor) * Math.min(1, Math.max(0, t));
  return { frozen: false, factor, touched: true };
}

poleTipLatitude picks the northern edge for a northern region and the southern edge for a southern one, so the same code mirrors itself across the equator. There is a test for exactly that, because a sign error here would have quietly made Patagonia safe:

it("mirrors for the southern hemisphere", () => {
  const south = { lat: -55, latNorth: -49, latSouth: -60 };
  expect(iceDaysFor(south)).toEqual(iceDaysFor(region));
});

The taper goes from 1.0 down to 0.25 at the centre, then to zero. In play it reads as a warning: your northern farms start producing less a few days before they go, and the region's panel shows the day the ice touches it, the day it freezes and what it still produces.

One job per day, scheduled at the start

The game server does not tick the world. Everything that happens at a moment is a row in a jobs table with an ends_at, and a worker picks rows up in order (that was the previous post). The ice fits that model perfectly, because I know every moment it will move before the match even starts:

export async function scheduleIce(tx: Tx, matchId: string, startsAt: Date, speed: number) {
  const dayMs = (86400 * 1000) / speed;
  for (let day = 1; day <= balance.match.lengthDays; day++) {
    const at = new Date(startsAt.getTime() + day * dayMs);
    await tx.insert(jobs).values({ matchId, kind: "ice_step", payload: { day }, startsAt, endsAt: at });
  }
}

Thirty rows, inserted in the same transaction that starts the match. speed exists so I can run a whole 30-day match in a few minutes for testing; the ice just runs faster with everything else.

Doing it this way has a nice property: if the worker is down for an hour, nothing is lost. When it comes back the overdue ice_step rows are simply the oldest jobs in the queue, and they run in order with the ends_at they always had. Production is credited up to that timestamp, not up to "now".

The freeze itself

The step is one function inside one transaction. In order, it:

works out which regions are tapering and which are freezing today,
locks every region it will touch, in ascending id order,
settles each one up to the job's ends_at, so the food and wood earned until the freeze are credited,
writes the new taper factors, and wipes the frozen regions.

Step 2 is the one I got wrong. Every other system in the game that touches more than one region locks them in ascending id order, which is the standard way to keep two transactions from waiting on each other forever. When I added the taper, the ice step started touching two lists of regions (tapering and freezing) and locked them as it went, in whatever order the lists came out. That is exactly the pattern that deadlocks against a battle or a convoy holding the same regions in the other order. Postgres would detect it and roll one side back, and the job would retry, but "it retries" is not a lock strategy. The fix, the same day, is one line and a comment so I never undo it:

// Lock every region we touch in ascending order (the lock order used everywhere) before changing any.
const touched = [...new Set([...taperChanges.map((t) => t.regionId), ...freezing.map((r) => r.regionId)])].sort();
for (const id of touched) settled.set(id, await settleAndLockRegion(tx, m.id, id, job.endsAt, m.speed, resourceMultOf(m)));

Then the freeze is deliberately brutal:

// Fully frozen: nothing and nobody survives. Stores, people and units all go to zero.
await tx
  .update(matchRegions)
  .set({ frozenAt: job.endsAt, iceFactor: 0, food: 0, wood: 0, stone: 0, special: emptySpecial(), popWorkers: 0, popSoldiers: 0, popOccupiers: 0, units: {} })
  .where(and(eq(matchRegions.matchId, m.id), eq(matchRegions.regionId, r.regionId)));

I went back and forth on this. A softer ice (people slowly die, stores slowly rot) is more "realistic", but it removes the decision. With a hard freeze on a schedule everybody can read, leaving late is a choice you made, not bad luck.

Making a hard rule feel less cruel

A hard rule needs a few release valves, or the late game is just a spreadsheet of who moved south first. Three small systems hang off the same step, and all three are described on the public how-to-play page:

Migrant columns. Before a region is wiped, a share of its people get out. The server walks the region graph breadth first, up to two hops, looking for the nearest empire that is still above water:

for (let h = 0; h < c.hops && !dest; h++) {
  const next: string[] = [];
  for (const id of ring) for (const n of regionById(id)?.neighbors ?? []) if (!seen.has(n)) { seen.add(n); next.push(n); }
  const here = next.filter((n) => ownerOf.has(n));
  if (here.length) dest = here[0]!;
  ring = next;
}

That owner gets a day to take them in for food or turn them away. It turns somebody else's disaster into your decision, which is the kind of thing a slow game needs more of.

Thaw pockets. Once or twice a match, a valuable region that should freeze within two days is spared for three more. The pick uses a random number generator seeded with the match seed and the day, so a replay of the match gives the same pocket, and every human player is told where it is. It is a short, public reason for people to fight over the north one last time.

Moving capitals. If the ice takes your capital, the capital moves at once to your most populous region that is still warm. If you have no warm land left, you are out of the match. That last rule came out of the nightly simulated matches I run against the live server: before it, a tribe whose last land froze could sit on in the standings with nothing, which helps nobody.

What I'd do differently

Write the taper first. The point-freeze version gave no warning at all, and adding the taper later cost a migration to put an ice_factor on every region row.
Decide the lock order on day one, and check it every time a function grows. The ice step was fine until it touched a second list of regions.
Keep the schedule as data. Tuning the ice has been a config change every time, never a code change, and the tests read the same config, so they keep me honest: "most of the map is frozen by week four, the tropics never freeze."

If you want to see the line move, every match has a public page with the map, and a new match starts every week at lastthaw.com. It's in early access, so if you try it and something feels wrong, I'd like to hear about it.

Turning old Facebook Page posts into a dated build log in Laravel

Matt — Sat, 31 Oct 2026 01:44:36 +0000

Most of the builders I'd love to have on Boat Build Log already wrote their log somewhere else. They posted it to Facebook, one update at a time, for years. Asking a retired man to retype ten years of posts into my site is exactly why he never signs up.

So I wrote an importer. This post is about the part that turned out to matter: taking messy, harvested posts, turning them into clean dated entries, and loading them with an Artisan command you can run ten times without making a mess.

The case study is Jim Norman's Jersey Girl, a 20 ft mini houseboat he built from 2015 on, posting every step to a public Facebook Page. I read that public Page slowly and imported it. It's now Jersey Girl on the site: 191 entries and 568 photos, March 2015 to August 2025.

Piece	Version
Laravel	13
PHP	8.3+
MySQL	8
Images	Imagick

Split the harvest from the import

The first version of this was for a different builder whose posts were friends-only. The only way in was Facebook's own "Download your information" archive, so I wrote bbl:parse-fb-export to read that zip. Then Jersey Girl came along, a public Page with no archive, and the harvest looked nothing like the export.

That's why the import is its own command and knows nothing about Facebook. Every harvest just has to produce the same JSON. Here's the contract, straight from the command's docblock:

[{ "date": "2024-05-14",            // required, YYYY-MM-DD
   "title": "Frames on the strongback",
   "text":  "markdown body",         // required (unless there are photos)
   "hours": 6.5,
   "phase": "framing",               // a phases.slug, optional
   "source_url": "https://...",      // attribution; a real link or null
   "source_ref": "fb-post:171...",   // stable identity, used to dedupe
   "photos": ["media/0001.jpg"],     // paths relative to --media
   "videos": [{"provider":"youtube","id":"..."}],
   "cover":  true }]

A data export, a forum thread, a WordPress blog (that adapter came three days later), or me typing it in by hand. Nothing past the JSON cares which.

The command itself is small to call:

protected $signature = 'bbl:import-log
    {--user= : id, handle or email of the account that will own the build}
    {--json= : path to the normalised entries JSON}
    {--media= : directory the photo paths in that JSON are relative to}
    {--build= : import into this existing build id instead of creating one}
    {--title= : title for the build being created}
    {--dry-run : validate and report, write nothing}';

The Laravel Artisan docs cover the signature syntax.

The date is the whole point

A build log is a chronology. If the dates are wrong, it's just a photo dump. So the importer has one rule I'd defend above all the others: logged_on comes from the post date, and nothing ever overwrites it.

That's the opposite of the normal upload path on the site. When a builder uploads photos by hand, I prefer the photo's EXIF date over the date they typed, because you shoot on Saturday and post on Sunday. For an import that reasoning flips. Facebook strips EXIF on upload, and the EXIF that survives a re-encode is more often the day somebody's scanner ran than the day of the work. So the import stores the photo with no taken date at all:

'taken_at' => null, // the post date is the truth here; stale EXIF would show under the photo as a lie
'sort_order' => $order++,

And a missing date never becomes today(). A hundred entries all dated today is the worst outcome I can think of, because it looks fine until someone reads it. Preflight refuses it:

if ($date === '') {
    $problems[] = "{$n}: no date. Resolve it in the harvest; this will not guess.";
    continue;
}
if (strtotime($date) > strtotime('today 23:59:59')) {
    $problems[] = "{$n}: {$date} is in the future.";
    continue;
}

Preflight is a separate pass over every row before anything is written. If entry 90 of 100 is bad, I want to know before entry 1 lands, not clean up half a log by hand.

Getting dates out of Jim's own words

Jim made this easier than most. Nearly every update starts the same way: "Houseboat update, Thursday, August 28, 2025 -- Jersey Girl in her new coat." So the normaliser, a Python script on my machine, reads the date out of the first 250 characters of the text, not from any timestamp.

He's a human typing, though, so it's not that clean. Some posts say "Sept. 29" with no year. One says "November 27, 2001", fourteen years before he started. The rules ended up as:

A year outside 2015 to 2026 is thrown away and treated as missing.
If he named a weekday, trust the weekday over the year he typed. People fat-finger the year far more often than the day of the week.
A date with no year borrows one from the nearest older dated post, bumping it if the month wraps past December.
Anything still undated goes to held.json for me to look at. It never gets a guess.

The weekday check is the bit I'm happiest with:

if year and wd:  # Jim sometimes typed the wrong year; trust the weekday he named
    want = WEEKDAYS.index(wd.group(1).lower())
    for y in (year, year - 1, year + 1):
        if dt.date(y, mon, day).weekday() == want:
            year = y
            break

The same script guesses a phase (framing, glassing, paint and so on) by scoring each post against a small vocabulary and taking the best match, not the first. "Deck" turns up in nearly every post, so first match put half the log in the deck phase.

Idempotency, because you will run it again

I knew I'd re-run this. I'd fix a date, fix a title, re-harvest a batch. Every one of those runs has to update what's there, not append a second copy of the log.

The export has no permalinks, so I couldn't key on URL. Instead every row carries a source_ref, and the column is unique per build:

$table->string('source_ref', 191)->nullable()->after('source_url');
$table->unique(['build_id', 'source_ref']); // per build: the same post can go into two builds

For Jersey Girl it's the Facebook photo id of the post's first photo (fb-jg:1697983821144093). For the export it's the timestamp plus a short hash of the content. The import looks that up first and falls back to the URL:

if ($row['source_ref']) {
    $entry = Entry::where('build_id', $build->id)
        ->where('source_ref', $row['source_ref'])->first();
} elseif ($row['source_url']) {
    $entry = Entry::where('build_id', $build->id)
        ->where('source_url', $row['source_url'])->first();
}

Photos follow a stricter rule: they're only attached to an entry that has none. A re-run must not double the album, and if the builder has since reordered or captioned his photos by hand, an import re-run shouldn't throw that away.

if ($entry->media()->exists() || (! $row['photos'] && ! $row['videos'])) {
    return;
}

Preflight also rejects a file where the same key appears twice. Otherwise the second row silently overwrites the first and the log comes out short with nothing said about it.

Two more decisions I'd make again. Attribution lives in entries.source_url, a column, never appended to the body. The entries table has a FULLTEXT index on title and body, and three hundred Facebook URLs in bodies would pollute every search on the site. And the command never publishes anything. The build is created as a draft, because the words belong to the builder and he hasn't seen them yet.

Photos are untrusted input

The photo paths in that JSON were written by a script that ran against a page I don't control. So preflight treats them as hostile. A ../../ in there would otherwise be read off disk and uploaded into a public build:

if ($rel === '' || str_contains($rel, '..') || preg_match('#^([a-zA-Z]:|[/\\\\])#', $rel)) {
    $problems[] = "{$n} ({$date}): photo path “{$rel}” must be relative and inside --media.";
    continue;
}

Each photo is then copied to a temp file and run through the same ImageProcessor the normal upload uses, so an imported photo gets the same web, thumbnail and print sizes as one a builder uploads. The harvest folder is the only copy of those files, so it stays untouched.

What went wrong

Plenty.

Reshares. Jim reshared his own older posts as memories, so the same text turned up twice with different photo ids. Different ids meant the dedupe let them both through. The fix was a second key on the normalised text (lowercased, letters and digits only, first 150 characters), and a reshare is skipped, never a second entry. A couple had already landed, so I deleted those by hand. Then the final re-derive pass only updates entries that already exist on the build, so a deleted reshare can't come back.

Photo-only posts. About a hundred of the Page's posts were a single photo with no caption. Each would have been an empty entry. Now a photo with no real caption joins the post before it.

Mojibake on the export path. Facebook's archive escapes UTF-8 one byte at a time, so "é" arrives as "Ã©" and every apostrophe in years of writing comes out as line noise. The fix walks it back through latin-1, guarded twice so it can't mangle text that was already right:

if (preg_match('/[^\x{0000}-\x{00FF}]/u', $s)) {
    return $s; // a character above U+00FF can't be this kind of mojibake
}
$bytes = @mb_convert_encoding($s, 'ISO-8859-1', 'UTF-8');
if (! is_string($bytes) || ! mb_check_encoding($bytes, 'UTF-8')) {
    return $s; // a genuine "café" stays a café
}

I lost a harvest. I'd read the whole Page once, kept it in memory, and lost it before it was saved. After that I harvested in small batches, saved each one to disk, and ran the import after every batch. Slower, but nothing was ever more than one batch from safe. A handful of items didn't make it in, like a Christmas greeting and a watercolor-class post, and I'm fine with that.

The launch isn't in the log. The Page has no posts with photos between 2020 and 2023, so the first launch in May 2021 isn't there, and I don't know the day. I'd rather leave it blank than invent it.

Would I do it again?

Yes. The harvest is throwaway and source-specific. The import is boring, strict and safe to re-run, which is what you want from the half that writes to production. The dates are the only thing I'd really fight for, and preflight is where that fight happens.

If you've got a build log sitting on Facebook or an old blog, have a look at what it would look like on Boat Build Log. Feel free to borrow the posts.json shape for your own importers too.

A strategy game that keeps running while nobody is online

Matt — Mon, 26 Oct 2026 14:52:55 +0000

I make Last Thaw, a free browser strategy game where up to a hundred players start with five settlers on a real map of Earth and have 30 real days to build an empire before an ice age, advancing from both poles on a public schedule, takes the land. It's in early access and I'm looking for people to test it.

The design rule that shaped the whole server is simple: there is no pause. You queue a building, start a research, send an army across the Atlantic, close the tab and go to work. When you come back eight hours later, all of it has happened, in the right order, whether or not anybody was logged in.

That sounds like a game loop. It isn't, and the first thing I learned was that treating it like one would have been the wrong call. This post walks through how the server actually does it: a jobs table ordered by finish time, regions that are settled lazily instead of ticked, and the locking mistakes I made along the way.

Why not just tick everything?

The obvious approach is a fixed tick: every N seconds, walk every region in every match, add production, advance timers, resolve whatever finished.

A match has 408 regions. With a handful of matches running at once you're doing thousands of row updates per tick, and almost all of them are doing nothing interesting. A region of forest in Siberia that nobody owns does not need to be rewritten every 30 seconds just so its wood number goes up.

So I split time into two kinds:

Things that happen at a moment. A building finishes, a tech completes, an army arrives, the ice moves one step south. These are discrete and they have an exact time.
Things that accrue continuously. Food, wood, stone and population growth. These are just rates times elapsed time.

The first kind goes in a jobs table. The second kind is never stored as "current", only as "the value at the last time someone looked".

The jobs table

Every timed thing in the game is a row with an ends_at. Queuing a building in a region is an insert:

await tx
  .insert(jobs)
  .values({
    matchId: m.id,
    playerId: p.id,
    regionId,
    kind: "build",          // build, train, research, mission, ice_step, storm, match_end...
    refId: buildingId,      // which building
    level,                  // the level it reaches
    payload: { cost, paid },
    startsAt,
    endsAt,                 // the only thing the worker cares about
  })
  .returning();

The ice is the same. When a match starts, every step of the ice schedule is inserted as an ice_step job, so the advancing glacier is just more rows. The end of the match is a match_end job. Nothing is special-cased.

A separate worker process polls once a second for anything due and completes it, strictly in ends_at order:

const due = await db
  .select({ id: jobs.id, matchId: jobs.matchId })
  .from(jobs)
  .innerJoin(matches, eq(matches.id, jobs.matchId))
  .where(
    sql`${jobs.completedAt} is null and ${jobs.cancelledAt} is null
        and ${jobs.attempts} < ${MAX_ATTEMPTS}
        and ${jobs.waitingFor} is null
        and ${matches.status} = 'running'
        and ${jobs.endsAt} <= now()`,
  )
  // Same instant: the match end goes last, so the final ice step
  // and arrivals of that moment still resolve.
  .orderBy(jobs.endsAt, sql`case when ${jobs.kind} = 'match_end' then 1 else 0 end`, jobs.id)
  .limit(500);

That ordering comment came from a real bug. Two jobs can share an ends_at to the millisecond (the last ice step and the end of the match are both scheduled from the same start time). With only ORDER BY ends_at, Postgres was free to finish the match first, and the final ice step then landed on a finished match. The tie-breaker makes the rule explicit.

Each job completes in its own transaction, and the completion is stamped with the job's own ends_at, not with now():

await db.transaction(async (tx) => {
  const [job] = await tx.select().from(jobs)
    .where(eq(jobs.id, id))
    .for("update", { skipLocked: true });   // another worker has it? skip
  if (!job || job.completedAt || job.cancelledAt) return;
  const [m] = await tx.select().from(matches)
    .where(eq(matches.id, job.matchId))
    .for("no key update");
  await complete(tx, m, job, (fn) => after.push(fn));
  await tx.update(jobs).set({ completedAt: job.endsAt }).where(eq(jobs.id, id));
});
for (const fn of after) await fn().catch(() => {});   // publish only after commit

Using job.endsAt as "now" inside the handler matters more than it looks. If the worker was down for ten minutes (a deploy, say), it wakes up to a backlog. Each job still resolves as of the moment it was supposed to, so a building that finished at 09:02 starts producing from 09:02, not from 09:12 when the worker got round to it. A late worker never changes the outcome, only when you hear about it.

The after list is the other half of that. Websocket messages ("your Granary is finished") are queued during the transaction and only sent once it commits. Early on I published inside the transaction, and a rollback would leave players with a notification for a building that didn't exist.

Poisoned jobs

If a handler throws, the transaction rolls back and the job is still due, so the next pass a second later tries it again. And again. One bad row was enough to fill the logs and, worse, it sat at the front of the queue in ends_at order.

The fix is an attempts counter written outside the failed transaction:

} catch (err) {
  log.error({ err, jobId: id }, "job failed");
  await db.update(jobs)
    .set({
      attempts: sql`${jobs.attempts} + 1`,
      lastError: String((err as Error).message ?? err).slice(0, 500),
    })
    .where(eq(jobs.id, id))
    .catch(() => {});
}

After five tries the job is parked (the attempts < 5 in the query above) and the error text is on the row for me to read in the morning. In practice nearly every parked job so far was a bug I wanted to know about, not something to retry harder.

I also found jobs left open on matches that had already finished, still sitting there as "due" forever. Now a separate loop cancels anything still open on a finished match once a minute.

Regions are settled, not ticked

Now the continuous half. A region row stores its stock (food, wood, stone, population) and a settled_at timestamp. That's it. The current value is a projection:

/** Pure projection of a row to `asOf`. Does not touch the database. */
export function projectRegion(row: MatchRegionRow, asOf: Date, speed: number, tech: TechEffects) {
  const traits = traitsOf(row.regionId);
  const effects = applyTechEffects(effectsOf(row.buildings), tech);
  const economy = settle(traits, economyOf(row, effects), elapsedSeconds(row.settledAt, asOf), speed);
  return { economy, rates: computeRates(traits, economy), effects };
}

settle lives in a shared package, so the browser runs the exact same function. When you look at a region, the client takes the row from the API and animates the numbers forward locally. No polling for "how much wood do I have now".

The rule that keeps it correct: settle before you change a rate. Anything that changes production (a building finishing, units being trained out of the workforce, a region changing hands) first locks the row and writes the projected values up to that instant:

export async function settleAndLockRegion(tx: Tx, matchId: string, regionId: string, asOf: Date, speed: number) {
  const [row] = await tx.select().from(matchRegions)
    .where(and(eq(matchRegions.matchId, matchId), eq(matchRegions.regionId, regionId)))
    .for("update");
  if (asOf.getTime() <= row.settledAt.getTime()) return row;   // already current
  const { economy } = projectRegion(row, asOf, speed, await ownerTechEffects(tx, row.ownerPlayerId));
  const [updated] = await tx.update(matchRegions)
    .set({ ...economyColumns(economy), settledAt: asOf })
    .where(and(eq(matchRegions.matchId, matchId), eq(matchRegions.regionId, regionId)))
    .returning();
  return updated;
}

When a building finishes, its handler calls this with job.endsAt. Everything before that moment is accrued at the old rate, then the building is added and the new rate applies from there. The unowned Siberian forest is never written until something actually happens to it.

Where it went wrong: lock order

Settling is cheap, but it takes a row lock, and once more than one region is involved you're in deadlock territory.

The case that bit me was a training order. Training can be supplied from other regions of the same player (the stock gets carried in). The first version locked the region you were training in, worked out what was short, then locked the supplying regions. Meanwhile an army coming home locked its destination region and then others, and the periodic loyalty pass walked a player's regions in its own order.

In one overnight match that combination deadlocked 14 times. Postgres detected each one and killed a transaction, the retry succeeded, and nobody lost anything, but it was a sign the design was wrong rather than unlucky.

The fix was boring and it worked: when an order might touch several regions, it locks every region of that player up front, in ascending region id, before doing anything else. Same order everywhere, no cycles. There's now a test that holds a lower region locked from another connection and checks the order waits on it without having grabbed a higher one first.

The match row has a smaller version of the same problem. Completing a job locks the match with FOR NO KEY UPDATE rather than FOR UPDATE. Inserting a job, an army or an order takes a key-share lock on the match through its foreign key, and FOR UPDATE conflicts with those. NO KEY UPDATE still serialises job completions against other match updates without fighting every insert.

Testing a 30-day game

You can't wait 30 days to see whether the ice reaches the equator on time. Every piece of simulation code asks one helper for "now":

export function matchNow(match: { clockOffsetSeconds: number }, realNow = new Date()): Date {
  return new Date(realNow.getTime() + match.clockOffsetSeconds * 1000);
}

In development a match can be pushed forward by bumping its offset, and the job query compares ends_at against now() plus that offset. Because jobs complete as of their own ends_at and regions settle to an explicit instant, skipping a day produces the same state as living through it. The full test plays a whole 30-day game this way in a few minutes.

What I'd tell myself at the start

Store moments as rows with a finish time. Store rates as a value plus a timestamp. Don't store "now".
Complete each event as of its own time, so a late or restarted worker can't change the result.
Publish after commit.
Count failures and park poisoned work instead of retrying forever.
Pick one lock order for multi-row writes on day one. You will need it.

If you want to see what this looks like from the player's side, the how-to-play page covers the timers and the ice schedule, and a new match opens every week at lastthaw.com. It's early access, so if you play it and something feels off, I'd really like to hear about it. Feel free to borrow any of this for your own timer-driven game.

Hand-researched boat specs as JSON, applied by slug in a seeder

Matt — Mon, 26 Oct 2026 14:52:44 +0000

I built a CLC Northeaster Dory in my garage in 2020. The hardest part of choosing it was not the woodworking. It was finding honest numbers: how long the boat really is, what it is built from, and how many hours it took people like me. That is why I built Boat Build Log, a Laravel 13 and MySQL 8 site where amateur builders log their builds and every design gets a page with real medians from those logs.

The logs need a catalog of designs to hang on. It has 1,052 design pages from dozens of designers, plus a few hundred production boats for people who restore rather than build. This post is about how the specs and write-ups for all of those got into the database, and how they stay there.

The problem

The catalog started as plain PHP arrays in database/seeders/data, one file per vendor, crawled from the designers' own listings. Each vendor publishes differently, so the files have different shapes. CLC gives a beam, Glen-L mostly does not, Devlin has his own format, and so on. BoatModelSeeder has a loader per shape and merges them:

$rows = array_merge(
    $this->fromVendorFile('clc.php', 'Chesapeake Light Craft', kitAvailable: true, withBeam: true),
    $this->fromVendorFile('glen-l.php', 'Glen-L Marine', designer: 'Glen-L Marine'),
    $this->fromDevlinFile(),
    $this->fromBowdidgeFile(),
    // ...a dozen more
);

Most rows came out as a name and a category. No length, no construction method, and a one-line description the seeder composes from whatever it knows ("17 ft rowing design from X. Plans and patterns are sold by the designer."). Those pages said nothing a searcher could use, so I kept them out of the index.

The fix was research by hand: look up every design on its designer's own site, write two paragraphs in my own words (never their marketing copy), and record LOA, beam, construction and the deep link to that design's plans page.

For Glen-L I did it the obvious way, by editing glen-l.php and a big descriptions.php keyed on brand and name. That worked for one file with one shape. It did not scale to the rest, for two reasons:

Nine loaders, nine row shapes. Adding columns to each would have meant touching every loader.
A good number of rows were never in a seed file at all. Builders can propose a design that is missing, and once approved it lives only in the database. There was no PHP array to edit.

Why per-designer JSON keyed by slug

Every row has a slug, whether it came from a seed file or a builder's proposal. Slugs are brand-scoped because Glen-L and CLC both sell a boat called Dory:

$slug = Str::slug(trim(($row['brand'] ?? '').' '.$row['name']));

So the research layer is keyed on that. One JSON file per designer in database/seeders/data/enrichment/, each a map of slug to entry. There are 72 files now. Here is the entry for my own boat, which ends up on the Northeaster Dory page (description trimmed):

"chesapeake-light-craft-northeaster-dory": {
  "description": "A 17 ft round-sided lapstrake dory for oars or sail...\n\nIt uses CLC's LapStitch method...",
  "loa_mm": 5182,
  "beam_mm": 1422,
  "construction_method": "lapstrake plywood",
  "plans_url": "https://clcboats.com/products/northeaster-dory",
  "source_url": "https://clcboats.com/products/northeaster-dory",
  "confidence": "high"
}

JSON because it is pure data, it diffs cleanly, and any script can read and write it. One file per designer because that is how the research happened: one designer's site open in a tab, working down their list.

source_url and confidence are never stored. They are notes for whoever checks a number later, usually me.

Applied last

Every deploy runs the seeder after migrations, so the seeder is the source of truth for anything it owns. The order inside run() matters:

foreach ($rows as $row) {
    // update existing rows, insert new ones
}

$this->creditDesigners();

// Last, so nothing above can write the composed one-liner back over a
// researched page.
$this->applyEnrichment();
$this->stripBlockedPlansLinks();

If enrichment ran first, the main loop would overwrite every researched description with the composed one-liner. Running it last gives the research the final say, and the vendor files stay exactly as crawled.

The merge rules

The rules are the interesting part, because "apply the JSON" is not one rule. A description always wins. A measurement only fills a blank:

$corrects = $e['corrects'] ?? [];

foreach (['loa_mm', 'beam_mm', 'construction_method',
          'hull_material', 'year_start', 'year_end'] as $field) {
    if (! empty($e[$field])
        && (empty($row->{$field}) || in_array($field, $corrects, true))) {
        $update[$field] = $e[$field];
    }
}

A figure verified by hand outranks one read off a page in bulk, and a research file should not quietly replace it.

But the research also found the catalog was wrong in places. A lot of the original lengths were nominal, read off the name. An "Archimedes 22" was stored as 22 ft 0 in when Devlin's own page says 22 ft 10 in. So an entry can list a field under corrects, which lets it overwrite. That gets used only where the designer's page plainly disagrees, about 200 times across all the files.

plans_url always replaces, because the whole point is to swap a designer's homepage for the specific design's page. designer_name fills a blank, or replaces a byline that just repeats the house name, or corrects one outright when listed in corrects. That last case exists because CLC's Shearwater 17 is Eric Schade's design and Bateau resells Richard Woods's catamarans under its own name.

Idempotency, missing slugs and duplicates

Running the seeder twice gives the same result. Every write is an update to a value the files already define, and the fill-a-blank rule means a second run finds nothing blank to fill.

A slug with no row is skipped, not inserted:

$row = DB::table('boat_models')->where('slug', $slug)->first();

if (! $row) {
    continue;
}

Enrichment describes the catalog; it does not add to it. Some entries target rows that exist only in production, through a builder's proposal, so on a fresh test database they quietly do nothing.

Quietly doing nothing is also the danger. If I renamed a design in a vendor file, its slug would change and its enrichment entry would silently stop applying. The guard is a test that seeds a fresh database and counts how many entries actually landed:

$this->assertGreaterThan(400, $applied,
    'Enrichment slugs do not match the seeded catalog.');

It is a blunt threshold, not a per-slug check, and I know it would miss a handful going stale. What it does catch is the case I worried about most, a whole file drifting.

Duplicates were a separate problem. The research turned up three designs that were in the catalog twice under different names, and ten rows that were never home-build designs at all (factory-built kayaks, a passenger ferry, a couple of cradles). The seeder only inserts and updates, and most of those rows were not in a seed file, so a migration removed them. Each old URL 301s from a config map, a duplicate to its survivor and the rest to the designer's shelf, because those pages were already in the sitemap.

One gap I have not closed: nothing checks for a repeated slug. A quick script finds no slug in two files today, but a repeat inside one file would never show up, because json_decode keeps the last value without complaint.

Validation

The files are data and will be re-researched, so the tests pin the contract of the files rather than any one boat. CatalogEnrichmentTest checks that:

every description is at least two paragraphs and 45 words, with no em dashes, en dashes or carriage returns
construction_method is one of the catalog's own words ("stitch and glue", "lapstrake plywood", "strip planked" and so on), so filters keep working
lengths and beams are integers between 300 mm and 40 m, and the beam is less than the length
a tampered length survives a second seed, which proves enrichment is not overwriting non-blank values
an enriched design page renders with at least two paragraphs and no noindex

The beam-wider-than-length check sounds silly, but with close to 2,000 entries typed by hand, a swapped pair of fields is exactly the kind of mistake I expect to make.

Nothing here needs more than what the Laravel seeding docs cover: DB::table() and a test calling $this->seed().

What went wrong along the way

The seeder redated every design on every deploy. The original loop used updateOrInsert with created_at = now(). Since it runs on every deploy, every design claimed to be new that morning. I only caught it when I started building a fortnightly digest of new designs, because "what is new" had no answer. Update and insert are now separate, and the dates belong only to the insert.

A migration fix got undone by the seeder. I standardized on American spelling with a migration. Three descriptions came back British in the same deploy, because the seeder ran after the migration and restored them from the seed data. Lesson: anything the seeder owns has to be fixed at the source, or it comes back.

A dead plans link. One designer's old site now serves something unrelated, and the "Where to get plans" button pointed at it. Clearing the column by hand would only last until someone proposed another design with the same link. So the seeder strips a short list of blocked hosts after enrichment, and the JSON entry keeps a plans_url_removed note explaining why, so I do not put it back.

How it shows on the page

The design page splits the description on blank lines and renders each as a paragraph. The meta description leads with the first sentence of the write-up. Splitting on ". " cut "designed by John C. Harris" after the initial, so the split now refuses to break after a lone capital:

preg_split('/(?<![A-Z])\.\s+(?=[A-Z0-9])/u', trim($model->description), 2)[0]

Below the write-up sits the section the whole site exists for: "What building a Northeaster Dory actually takes", medians from logged builds, not the designer's estimate. The researched specs fill the spec panel, the plans button goes to the design's own page, and a design with a length, a construction method and a designer counts as having specs.

Once every design had a real description, I dropped the thin-content gate and put the whole catalog in the sitemap.

Would I do it again?

Yes. The vendor files stay as crawled, the research sits in its own reviewable layer, and the seeder applies one over the other in a fixed order on every deploy. The weak spots are the blunt slug-drift test and the missing repeated-slug check, and both are on my list.

If you are building a boat and want your hours to count toward those medians, the logs are at boatbuildlog.com.

How I turned real-world borders into 408 game regions of roughly equal value

Matt — Mon, 19 Oct 2026 00:30:57 +0000

I've been building Last Thaw, a free browser strategy game that plays out on a real map of Earth over 30 real days while an ice age creeps in from both poles. It's still in beta, and I'm looking for people to test it, so if that sounds like your kind of thing, come break it.

This post is about the very first problem I had to solve: the map. Not drawing it, but carving it up.

The problem with real maps

If you hand a strategy game a real political map, you get a terrible board. Russia is one tile the size of a continent, and Luxembourg is a tile you can't click on. Use states and provinces instead and it flips: there are thousands of them, and the US alone has 50 states.

What I wanted was around 400 regions, each worth roughly the same to the player, that still follow real borders so you can look at the map and say "that's me, I'm in Nouvelle-Aquitaine" or "I'm in Western Australia". Big countries just contain more regions.

Everything runs as a one-off Node script that writes a single world.json the game ships with.

Piece	Version / value
Source data	Natural Earth admin-1 (states and provinces), 10m
Node + tsx	Node 22, tsx 4.20
Geo libraries	d3-geo 3.1, topojson-server 3.0, topojson-client 3.1, topojson-simplify 3.0
Target	400 regions (accepted range 380 to 420)
Result	408 regions in 149 countries, 312 sea routes, 838 KB of JSON

Step 1: define "value"

Area alone is a bad measure. A square kilometre of Siberian tundra isn't worth a square kilometre of the Po valley, and the game's ice age makes the far north worth even less over time. So each province gets a value from three things: its area, a latitude factor and a desert factor.

function latitudeFactor(absLat: number): number {
  if (absLat < 50) return 1;     // most of the populated world
  if (absLat < 60) return 0.6;   // northern Europe, southern Canada
  if (absLat < 70) return 0.25;  // the ice reaches here early
  return 0.05;                   // Arctic: nearly worthless
}

const areaKm2 = d3.geoArea(feature) * EARTH_RADIUS_KM ** 2; // steradians -> km2
const [lon, lat] = d3.geoCentroid(feature);
const desert = inDesert(desertBoxes, lat, lon) ? 0.5 : 1;   // Sahara, Gobi, Atacama...
const value = areaKm2 * latitudeFactor(Math.abs(lat)) * desert;

The deserts are just hand-drawn lat/lon boxes in a JSON config (18 of them, "Sahara west", "Atacama", "Australia interior" and so on). Crude, but it's a game, not a GIS project, and a box you can read and edit beats a raster lookup you can't.

Step 2: build a topology so borders are shared

This was the step that made everything else possible. GeoJSON stores every polygon on its own, so two neighbouring provinces each carry their own copy of the border between them. TopoJSON stores that border once, as an "arc", and both provinces point at it.

// Shared borders become shared arcs; quantizing snaps nearly-equal points together.
const topo = buildTopology({ p: provinces }, 1e5);
const ps = presimplify(topo);                 // adds a simplification weight to every point
const neighbours = topoNeighbors(ps.objects.p.geometries); // adjacency for free

From that you get three things almost for free:

Adjacency. Two provinces are neighbours if they share an arc.
Shared border length. Sum the haversine length of the arcs two provinces share.
Coastlines. An arc owned by exactly one province is coast.

// An arc with a single owner has no province on the other side: it's coastline.
for (const p of provs) p.coastal = p.arcs.some((a) => arcOwners[a].length === 1);

Step 3: clean up the edges of the world

Before merging anything, two cleanup passes:

Tiny isolated islands go. Anything under 2,000 km² with no land neighbour is dropped. Nobody wants to defend a rock.
Micro-states merge into a neighbour. A country worth less than 0.25% of the world's total value joins the neighbour it shares the longest border with, unless it's at least 25,000 km². That size floor is what keeps Switzerland, Ireland, Cuba and Sri Lanka as their own regions instead of vanishing into a neighbour.

Step 4: merge provinces inside each country

Now the main loop. Each surviving country gets a target number of regions in proportion to its share of total value, with a minimum of one:

const target = Math.max(1, Math.round((scalar * TARGET_REGIONS * country.value) / totalValue));

Then, inside that country, it's a greedy merge: take the lowest-value unit, glue it onto its lowest-value neighbour, and repeat until the country is down to its target. Trimmed down, it looks like this:

while (true) {
  const low = items.filter((w) => !w.fixed).sort((x, y) => x.value - y.value)[0];
  if (!low) break;
  // Stop once we're at target, the smallest piece isn't too small, and it touches something.
  if (items.length <= target && low.value >= minRegionValue && !isIsolated(low, regionOf)) break;

  const host = smallestAdjacent(low) ?? nearestWithin(low, 1500 /* km */);
  if (host) absorb(host, low);              // members, value, area and centroid all add up
  else if (low.areaKm2 >= 20_000) low.fixed = true; // Alaska, Hawaii, Svalbard stand alone
  else orphans.push(low);                   // re-homed later by longest shared border
}

Merging into the smallest neighbour, not the biggest, is what keeps things even. If you merge into the biggest you get one blob that eats the country.

The centroid trick is worth calling out. Averaging lat/lon breaks near the date line, so each unit carries an area-weighted 3D vector instead, and merging two units is just adding their vectors:

function toVec(lat: number, lon: number, weight: number): Vec3 {
  const cl = Math.cos(lat * DEG);
  return [weight * cl * Math.cos(lon * DEG), weight * cl * Math.sin(lon * DEG), weight * Math.sin(lat * DEG)];
}
// absorb(): host.vec = addVec(host.vec, other.vec); the centroid is fromVec(host.vec)

Step 5: hit the count

Because every country rounds its target and gets at least one region, the first pass never lands on 400. So the whole merge re-runs with a scalar until the count falls inside 380 to 420:

let scalar = 1;
let pass = runPass(scalar);
for (let iter = 0; iter < 12; iter++) {
  const n = pass.works.length;
  if (n >= 380 && n <= 420) break;
  scalar *= 400 / n;        // overshot? shrink every target a little, and vice versa
  pass = runPass(scalar);
}

It usually settles in two or three passes.

Step 6: names, terrain, resources, sea routes

A region made of one big province keeps that province's name. One made of three or more small departments or counties borrows the parent region's name from Natural Earth, which is how a pile of French departments becomes "Nouvelle-Aquitaine". If a region ends up holding an entire country, it just takes the country's name.

Terrain and resources are seeded randomness with real constraints: tundra above 62°, desert inside the desert boxes, fish only on coasts and rivers, horses only on plains and hills. The RNG is seeded per region id (rngFor("lastthaw-1", "fr-nouvelle-aquitaine:resources")), so regenerating the map doesn't reshuffle what's already there. Then 183 hand-written overrides fix the things randomness gets wrong, mostly terrain and rivers: Switzerland and the Tirol are mountains, not whatever the dice said.

Sea routes link each coastal region to its two nearest coastal regions within 2,500 km, plus 47 hand-picked crossings like the Bering Strait. A final sanity check refuses to write the file if any region is isolated, has a one-way link, or has an empty path.

Step 7: fit the SVG into a byte budget

The map renders as SVG in the browser, so every region needs a path, and the whole lot has to stay small. I gave the paths a 700 KB budget and simplified to fit it. The catch is that simplifying two neighbours separately leaves slivers and gaps between them. The fix is the same topology from step 2:

Shared borders all use one uniform simplification weight, so both sides of a border drop exactly the same points and stay watertight.
Coastlines of oversized regions get simplified harder, one arc at a time, until no single path is over 4.5 KB.

One bug I lost an evening to: simplification can leave a ring with almost no area, and d3-geo then decides the polygon contains a pole and fills the entire sphere. If you ever see one country paint the whole map, that's why. The generator now drops near-zero rings and fixes the winding order before drawing.

How even did it come out?

Honestly, roughly. Value is normalised so the average region is 1.0:

	Value
10th percentile	0.34
Median	0.88
90th percentile	1.54
Max	7.04

The long tail comes from the "at least one region per country" rule and from huge single provinces you can't split without inventing borders. Western Australia is one province, so it's one region. The low end is small countries that survived the size floor, like Rwanda and Haiti at about 0.1.

The other side effect is that northern Europe comes out coarse: the latitude factor hits it, so Germany is a single region while the US has 31. It's on my list. That's the beauty of the whole thing being one script with a few constants at the top, though: change a factor, re-run, look at the preview page, repeat.

Wrapping up

If you're building anything on a real map, the topology step is the part I'd steal. Shared arcs give you adjacency, border lengths, coastlines and gap-free simplification, all from one data structure.

And if you want to see the result, the map is live at lastthaw.com. Last Thaw is still in beta and I'm looking for testers, so sign up, pick a spot on the map and watch the ice come for it. The how to play page covers the rest. Feel free to borrow any of this for your own map, and tell me what breaks.

Posting from a shed with one bar of signal: an offline write queue in plain JS

Matt — Sun, 06 Sep 2026 03:11:27 +0000

I run boatbuildlog.com, a site where people keep a dated log of a boat they are building. Photos, notes and hours, entered day by day over the two or three years a build actually takes.

The important thing about that sentence is where the typing happens. Not at a desk. It happens standing in a metal shed, a barn or a driveway, on a phone, with sawdust on it, on one bar of signal or none at all.

Which makes the ordinary web assumption wrong. Normally a failed POST is an inconvenience and the user retries. Here, a failed POST means someone wrote up an afternoon of work, hit Post, watched it fail, and learned that logging their build is a thing that loses their writing. They do not come back to it. The feature does not degrade, it dies.

So the rule became: a post is never allowed to fail destructively.

The queue

The composer submits through fetch. On any network failure the entry and its photos go into IndexedDB and replay when the connection returns.

IndexedDB rather than localStorage for one reason: Blobs. A log entry is mostly photographs, and localStorage holds strings. Base64ing a few 4 MB phone photos into a 5 MB quota is not a plan. IndexedDB stores the Blob itself, and it survives a browser restart, which matters when the phone gets put in a pocket and the tab is gone by evening.

var DB = 'bbl-offline', STORE = 'entries', VERSION = 1;

function open() {
  return new Promise(function (resolve, reject) {
    var req = indexedDB.open(DB, VERSION);
    req.onupgradeneeded = function () {
      var db = req.result;
      if (!db.objectStoreNames.contains(STORE)) {
        db.createObjectStore(STORE, { keyPath: 'id', autoIncrement: true });
      }
    };
    req.onsuccess = function () { resolve(req.result); };
    req.onerror = function () { reject(req.error); };
  });
}

No framework, no wrapper library. The whole site ships hand-written CSS and a handful of plain JS files, because the server it runs on has no Node on it at all and therefore has no build step by design. That constraint turned out to be a gift roughly as often as it was a nuisance.

The part I got wrong first: the CSRF token

The obvious implementation stores the whole form, token included, and replays it verbatim. That works beautifully in testing, where "offline" lasts about eleven seconds.

In the shed it lasts until the drive home. A queued entry can sit for days. By then the CSRF token is stale, the replay is rejected, and the failure looks exactly like a bug in the queue rather than an expired token.

So the token is deliberately not stored with the draft. At replay time the queue fetches the composer page and reads a fresh one out of it:

var m = html.match(/name="_token"\s+value="([^"]+)"/);
if (!m) throw new Error('no csrf token, probably signed out');

That error case is doing real work. If the session expired while the entry sat in the queue, there is no token to find, and the right move is to say so and keep the draft, not to silently discard it. The queue's entire promise is that your writing is still there.

The service worker cache bug that ate two "your fix didn't work" reports

Separate lesson, same project, and this one cost me more.

The service worker is deliberately narrow. It caches the static shell and an offline fallback page. It never caches HTML, because pages here are per-user and moderation-sensitive, and serving one builder a cached page belonging to a different session is a much worse bug than being offline.

The shell is cache-busted with a ?v=<mtime> stamp. The first version of the fetch handler matched on the pathname:

// The bug:
if (SHELL.indexOf(url.pathname) !== -1) {
  e.respondWith(caches.match(url.pathname)); // query string thrown away
}

/css/app.css?v=1755 and /css/app.css?v=9902 both normalise to /css/app.css, hit the cache, and return the file from install time. Forever. Every deploy asked for a new URL and got handed the old file anyway.

CSS changes were therefore invisible to anyone who had ever loaded the site once, and perfectly visible to me in a fresh incognito window. I shipped the same fix twice and got told twice that it had not worked.

The fix is to match the full request, so a new ?v= is a deliberate miss:

return cache.match(req).then(function (hit) {   // req, not url.pathname
  if (hit) return hit;
  return fetch(req).then(function (res) {
    if (res && res.ok) cache.put(req, res.clone());
    return res;
  }).catch(function () {
    return cache.match(url.pathname);   // offline: install-time copy
  });
});

Note the fallback still matches on pathname, but only after the network has failed, which is the one moment when "some version of the stylesheet" beats "no stylesheet".

The worst part was not the CSS. The JS files carried no ?v= stamp at all, so they were frozen at install-time versions for every returning visitor, and nobody reports a stale JS file the way they report a stale colour. The one that mattered was the proof-of-work solver on the signup form. Change the challenge server-side and returning visitors keep solving the old one against the new server, and silently cannot register. There is no error to see. Signups just quietly stop.

Now every asset URL goes through one helper and a test fails the build if a reference is added without a stamp. That test exists because I could not trust myself to remember, and the failure mode is invisible.

Takeaways

If losing a user's input is fatal to the habit you are trying to build, the write path needs a queue, not a retry button.
Store Blobs in IndexedDB, not base64 in localStorage.
Do not store CSRF tokens with a queued request. Fetch a fresh one at replay.
A service worker's cache key is the full request. If you cache-bust with a query string and match on pathname, you have built a cache that can never be invalidated.
Assets that fail loudly get reported. Assets that fail silently, like a proof-of-work solver, need a test.

The site is boatbuildlog.com if you want to see what all this is in aid of. If you are building a boat, it is free, and it would like your log.