DEV Community: Daniel Pertu

A preference is not a verdict: adding a third lane without letting it argue with the rules engine

Daniel Pertu — Mon, 28 Sep 2026 08:46:22 +0000

Munchable scans a barcode and tells you whether a product suits the gut conditions on your profile. People kept asking for something next to that: not "is this safe for my IBS", but "I do not want to buy things with artificial colours in them, tell me when there are some".

The cheap way to ship that is to add it as another condition. We already have a rules engine that takes a profile of conditions and returns a verdict per condition, so an eighth entry in the enum called "healthy" is maybe an afternoon of work.

It is also wrong, and the reason is worth more than the feature.

A preference is not a health claim, and the engine knows the difference

A condition rule set answers a clinical question using clinical guidance. The engine reconciles the per-condition results, detects conflicts between them, and takes the worst tier as the overall verdict, because when two conditions disagree about a product the cautious one has to win.

Drop a preference into that machinery and it inherits all of it. "Contains an artificial colour" would argue with a low FODMAP assessment as though the two were the same kind of statement, and the worst-tier rule would let a colouring agent out-vote a clinical result. The answer on screen would be a single word covering two questions that have nothing to do with each other.

So the healthy filter is not a condition. It is a third lane beside the conditions and the allergen layer, and it has three properties none of the others have:

It runs only for a profile that switched it on, and is absent from the result entirely for everybody else.
It never produces a verdict word. The conditions own "Good fit", "Caution" and "Avoid", and this layer is not allowed to use them.
It never clears a product. It can only say what it found.

That last one is the whole design, and it lives in about ten lines of presentation code.

Never green

/** The row title: the finding count, or the quiet state. */
export function healthTitle(check: HealthCheck): string {
  const n = check.hits.length;
  if (n === 0) return 'Nothing you asked about';
  return n === 1 ? '1 thing you asked about' : `${n} things you asked about`;
}

/** The word on the right of the row. Never a verdict word. */
export function healthLabel(check: HealthCheck): string {
  return check.hits.length === 0 ? 'None found' : 'Found';
}

"Nothing you asked about" rather than "nothing to worry about". The filter reads an ingredient list and whatever nutrition figures the row happens to carry. "Nothing you asked about" is a true sentence. "Nothing to worry about" is a claim about the whole pack that no ingredient list can support.

The colour follows the same rule: amber when something is found, muted grey when nothing is, and deliberately never green. A green tick beside "none found" reads as approval of the product, and this layer has no opinion about the product. The icon changes too, so the state is never carried by colour alone.

The tone is different from the allergen rows on purpose. Allergens are safety critical, so they hedge: "not mentioned" must never be read as "free from". The healthy filter does not hedge at all, because the reader set this preference themselves. They asked not to see artificial colours, the pack has one, and naming it is the entire job. Stacking a caveat under a line the reader requested is noise pretending to be diligence.

The tier is what makes it useful

The obvious implementation of "flag additives" flags everything. Citric acid and lecithin are on tens of thousands of products in our catalogue. A filter that fires on "this is an additive" fires on most of the aisle, and a warning on nearly every product is not a warning, it is wallpaper.

So each additive carries a concern tier, and only one of the three ever fires:

tier	behaviour
`flagged`	named, when the preference covering its class is on
`notable`	never fires, listed as context under the row
`benign`	silent

There is a second, quieter benefit. A classification is an assessment. Before this existed, every one of those additives showed up on the result screen's "not yet assessed" list and in the curation backlog, for every user, whether or not they had the filter on. "This is citric acid and there is nothing to say about it" is an answer, not a gap.

You can see that layer working on the public question pages, which are generated by the same engine: Does E330 cause reflux? and Does E270 cause reflux? are both additives that a naive filter would shout about, and neither page invents a concern. The full index is here.

What automation is allowed to touch

The additive map grows two ways: by hand, and through the same curation pipeline that extends the rest of our taxonomy. The boundary is asymmetric on purpose.

An automated row may classify an additive, and may file it as notable or benign. It may never mark one flagged.

Deciding what the filter is for is a product judgement, and a wrong one puts a caution on somebody's shopping. Widening the silent set is a cleanup. Widening the loud set is a claim. So the loud set grows by hand, with a person on it, which is the same rule the rest of the engine follows and which we wrote about in AI proposes, the engine disposes.

Two small structural choices that saved trouble

One array, not a boolean and a list. The on-device profile stores a single array of enabled preferences, and an empty array means the filter is off. A boolean beside a list is two sources of truth for one question, and they will disagree: "on, with nothing selected" is a filter that checks nothing while the settings screen cheerfully says it is working.

A Record over the id type, not a lookup that can miss. Every preference the engine knows about must have a card in the app:

/**
 * `Record` over `HealthPreferenceId` is what guarantees every engine preference
 * has a card: leave one out and this file does not compile, which is a better
 * place to find out than a crash on the settings screen.
 */
const META: Record<HealthPreferenceId, Omit<HealthPreferenceMeta, 'id'>> = { ... };

Adding a preference to the engine and forgetting the UI is now a build failure rather than a blank row somebody finds in production.

And the thresholds are somebody else's. The nutrient preferences compare against the UK FSA front-of-pack red bands, per 100 g, unchanged. A published, citable standard on purpose: the number a shopper has already seen on the front of thousands of packs is the number this filter should agree with. Inventing our own cut-off would mean disagreeing with the label in their hand, and being right would not help.

The general shape

If you are bolting a preference system onto something that already produces a judgement, the questions worth asking early are: can this new layer change the existing verdict (ours cannot), can it clear something (ours cannot), and does it use the same vocabulary as the thing that can (ours may not). Three noes, and the two systems can sit on the same screen without either one borrowing the other's authority.

The public conditions pages show the side of this that does give verdicts, for contrast. The difference in tone between those pages and a preference row is the whole point.

We stopped converting our price at checkout and wrote one figure per currency instead

Daniel Pertu — Mon, 28 Sep 2026 08:44:55 +0000

Munchable is a paid app, and for a while its price was one number in one currency with a conversion bolted on at the end. You read £10 on the pricing page, clicked through, and Stripe's Adaptive Pricing worked out a local figure on its own checkout page using whatever the rate was that morning.

That arrangement has one obvious defect and one subtle one.

The obvious one: the number on the page is not the number on the payment screen. That is the moment people abandon a checkout, and being right about the exchange rate does not help you.

The subtle one: there is no answer to "how much is Munchable in Sweden?". There is only "about this much, today". You cannot put it in an email, an ad, or an app store screenshot, because it was never a price. It was the output of a conversion.

So the price list became a table, one fixed figure per currency, and both the page and the charge read it.

You can see it on munchable.app/#pricing. If you have a VPN, switch country and reload: the figure changes and then stays put, including on the payment screen.

One function produces the number, twice

/**
 * The price in `currency`, in that currency's minor units, derived from an
 * amount of GBP pence.
 *
 * This is the real price, not a preview of one: the same call feeds the pricing
 * table, the paywall and the Checkout Session. Changing it changes what people
 * are charged.
 */
export function priceIn(pence: number, currency: DisplayCurrency): number

The comment is the design. There is no display path and no billing path, there is one function, and the Checkout Session is created for exactly what the landing page printed. A country resolves to a currency, that currency has one price, and that price does not move between the shelf and the till.

The table is authored in GBP pence and derived once per currency, so adding a market is two edits: a currency definition and the country codes that use it. Everything else falls out of those two maps.

Rounding up is not the same as rounding

An exchange rate produces a number like 12.16. Nobody prices anything at 12.16. Prices are a shape, and the shape is different per currency:

function ceilToRetail(amount: number, digits: number): number {
  const EPSILON = 1e-9;

  if (digits === 0) {
    // 100 above a thousand, 10 above a hundred, whole units below that.
    const step = amount >= 1000 ? 100 : amount >= 100 ? 10 : 1;
    return Math.ceil((amount - EPSILON) / step) * step;
  }

  const step = 1 - Math.pow(10, -digits); // 0.99 for 2dp, 0.9 for 1dp
  return Math.ceil(amount - step - EPSILON) + step;
}

Two branches, because currencies are written differently. A currency with decimals goes to the next .99, so 12.16 becomes 12.99. A currency without decimals runs into the thousands, and a yen price of 2,246 reads as the output of a conversion rather than as a price, so it steps to a round figure the way the prices on a shelf there do.

The epsilon is not decoration. Without it a value that is already exactly on a boundary gets nudged up by a whole step by binary float error, which is how a price quietly gains a hundred yen one deploy.

The property the rest of the module depends on is that this function never returns less than it was given. We are paid in the customer's currency and settle in sterling, so a conversion fee comes out on the way back, and the published rates drift between refreshes of the table. A small buffer plus the round-up absorb both, so ten pounds of list price stays roughly ten pounds of settled revenue rather than nine sixty.

Discounts round the other way

This is the part that surprised me when writing it. A discount is not a price, and applying the price rounding to it is a bug.

/**
 * The opposite rounding to priceIn, for the opposite reason. A price is
 * rounded up so the figure covers the conversion back to sterling; a discount
 * rounded up is a promise we then fail to keep, so this converts at the plain
 * mid-market rate and rounds DOWN.
 */
export function discountIn(pence: number, currency: DisplayCurrency): number

A price rounded up costs the customer a few cents and covers our fee. A discount rounded up means we advertised credit we do not honour. The buffer that protects the price is exactly the wrong thing to apply to a reward, so discountIn drops both the buffer and the round-up and truncates instead. Same table, same rate, opposite direction, because the two numbers are promises to different parties.

The unlisted country is the interesting default

Not every country is in the map, and the fallback is the base currency:

/**
 * Any country not listed falls back to GBP, which is both the safe default (it
 * is the currency we settle in) and correct for the UK audience that makes up
 * most of our traffic. An unlisted country therefore reads a pound price and is
 * charged in pounds: the same price twice, which is the promise that matters.
 */

The temptation with a fallback is to be clever: guess a currency from the locale, or convert at request time from a rate feed. Both reintroduce exactly the thing we removed, which is a number that exists only for the duration of one request. A visitor in an unlisted country seeing a pound price and paying a pound price has a worse currency experience and a correct one. Adding their country to the map is how that improves, and it is a code change with a review on it rather than an inference.

The same reasoning, incidentally, is why the rate feed stayed out. The rates are an input to authoring the table, not a runtime dependency: they are sourced from a dated set of reference rates and refreshed deliberately when one moves enough to matter. Rendering a pricing page does not make a network call to find out what to charge.

Zero is not a price

One guard worth stealing:

if (pence === 0) return 0;

Without it, the round-up turns the free tier's £0 into "€0.99", which advertises a price for the plan whose entire point is that it does not have one. We wrote about that family of bugs separately in Free is free everywhere, and four other rounding bugs in a price formatter, and about the trap of a formatter that assumes hundredths in Intl says zero decimals, Stripe wants hundredths, and the shelf wants ¥2,300.

What changed with this one is smaller than any of those and worth more: the price stopped being computed at the moment of payment. It is now a fact about a currency, written down, testable, and quotable in a sentence.

Go and look: munchable.app/#pricing. Whatever it says for your country is what the checkout will say, and it will still say it next month.

Our support desk is a catch-all MX record, and the plus address is the thread

Daniel Pertu — Mon, 28 Sep 2026 08:43:17 +0000

Munchable is a gut health scanner. People write to us about billing, about a barcode that came back wrong, and about symptoms they are trying to manage. That last category is why we did not buy a helpdesk: a support thread on this product routinely contains a health condition, and posting every one of those conversations into a third party's SaaS is a privacy decision, not a procurement decision.

So support is a table in our own database with four doors into it. This is what the email half of that turned out to involve, because email is the door that fights back.

You can walk through the front of it at munchable.app/support. File something, and you get a reference back. Reply to the email it sends you, and the reply lands on the same thread.

Four doors, one service

A ticket can be created by the web form, by the app, by an inbound email, or by an operator in the admin panel. Every one of those goes through a single module.

// apps/web/lib/support/ticket-service.ts
//
// The one data-access layer for support_tickets / support_messages. Every door
// into support goes through here, so ownership checks, status transitions and
// ordering are written once rather than four subtly different times.

It returns DTOs, never rows. That sounds like ceremony until you notice what is on the row and not on the DTO.

The thread token is the whole trick, and it never leaves the server

When we email you about a ticket, the Reply-To is not our support address. It is our support address with a token in the plus part:

export function threadReplyTo(threadToken: string): string {
  return `Munchable Support <${SUPPORT_LOCAL}+${threadToken}@${SUPPORT_DOMAIN}>`;
}

export function threadTokenFromAddress(address: string): string | null {
  const match = /^([a-z0-9._-]+)\+([a-z0-9]{16,64})@(.+)$/i.exec(address.trim().toLowerCase());
  if (!match) return null;
  const [, local, token, domain] = match;
  if (local !== SUPPORT_LOCAL || domain !== SUPPORT_DOMAIN) return null;
  return token;
}

Your mail client keeps that address on every reply in the thread, which is how a message with no subject, sent from a phone, three weeks later, still knows which conversation it belongs to.

The token is a secret. It is on the ticket row and it is deliberately absent from every DTO the service returns, so no route handler can leak it into a JSON response by accident. Anyone holding it can post into that thread.

The reference people actually see is a different thing, derived rather than stored:

/** MU-XXXXXX, from the random half of the ticket's ULID. Distinctive in an
 *  email, not a usable handle: reading a ticket still needs the full id. */
export function ticketRef(id: string): string {
  return `MU-${id.slice(-6).toUpperCase()}`;
}

The MX record is a catch-all, so the routing is ours

Mail for the whole domain lands on one webhook. What happens next is decided by the recipient: a plus-addressed reply appends to its ticket, mail to the support, bugs and feedback addresses opens a new ticket, and everything else is forwarded on with Reply-To set to the sender.

The rule that took an incident to learn: mail that becomes a ticket is not also forwarded. Forwarding it as well puts the same customer in a personal inbox and in the support queue, and then two replies go out, or the same person answers it twice a day apart. The operator gets an alert email instead, and the alert points at the ticket rather than containing it.

Replies arrive with the whole conversation stapled underneath

An email reply contains the reply, then a quoted copy of everything that came before, then possibly a signature. Store that verbatim and every thread grows quadratically, and you re-store your own outbound mail, thread token and all, once per round trip.

Stripping the quoted tail is a heuristic, so the interesting part is which way it is allowed to be wrong. Cutting too much loses what a customer wrote, which cannot be recovered. Leaving a few quoted lines in is untidy. So the trimming only cuts at unambiguous markers:

const QUOTE_MARKERS: RegExp[] = [
  /^On .{5,120}\bwrote:\s*$/i,
  /^-{2,}\s*Original Message\s*-{2,}\s*$/i,
  /^_{5,}\s*$/,
  /^From:\s?.+@.+$/i,
  /^Sent from my \w+/i,
  /^-{3,}\s*Forwarded message\s*-{3,}\s*$/i,
];

Three rules around those markers do most of the work:

A marker in the first line is ignored. A reply that opens by quoting us is quoting us on purpose.
A > line only starts the quoted tail if the run of quoted lines reaches the bottom of the message. One quoted line in the middle is someone answering inline, and cutting there would delete the rest of what they said.
If the cut would leave nothing, the original text is kept. An over-eager trim must never turn a real message into an empty one.

const trimmed = body.trim();
return trimmed || normalized.trim();

Two failure modes that are specific to email

Robots reply too. Out-of-office autoresponders, bounce notifications and "we received your message" acknowledgements all arrive looking like a customer. If one of those opens a ticket and the ticket sends a confirmation, and their responder answers the confirmation, you have built a loop with somebody else's mail server. Inbound mail is checked for the headers that mark it automated (Auto-Submitted, Precedence and friends) before any of it turns into a conversation.

Webhooks retry. A delivery that times out halfway is redelivered, and the naive handler appends the same customer message twice. Each event is claimed with a short-lived key before processing and confirmed after, so a retry of an in-flight event is dropped rather than duplicated, and a genuinely failed one is released to be tried again.

Neither of these is clever. Both are the kind of thing you only write down after seeing it happen once.

What it bought

Support conversations live in the same Postgres as everything else, subject to the same deletion rules as the rest of a person's data, which matters when the account deletion endpoint has to actually mean it. There is no seat-priced tool in the loop. And the statuses are ours, so the queue can use the operator's vocabulary while the customer sees theirs:

export const TICKET_STATUS_LABELS: Record<TicketStatus, string> = {
  open: 'Open',
  awaiting_user: 'Waiting on you',
  resolved: 'Resolved',
  closed: 'Closed',
};

export const TICKET_STATUS_LABELS_ADMIN: Record<TicketStatus, string> = {
  open: 'Needs a reply',
  awaiting_user: 'Waiting on them',
  resolved: 'Resolved',
  closed: 'Closed',
};

Same four states, two different sentences, one Record that will not compile if a fifth status appears without both of them being written.

Try the support form if you want to see the round trip. The reply that comes back will have a reference on it, and a Reply-To that is not the address you would guess.

Our reels compute their own verdicts, so a video cannot promise what the app would not say

Daniel Pertu — Mon, 28 Sep 2026 08:38:47 +0000

Munchable is a gut health scanner: you scan a barcode, it tells you whether that product fits the conditions on your profile, and it names the reason. We make short vertical videos for it. Sixteen of them at the moment, each one a phone, a shopping aisle, a scan, and a result card that says "Good fit", "Caution" or "Avoid".

A video like that is a claim. It is also the only artefact in the whole product that nobody re-renders when the code changes. A screen recording made in March is still sitting on a feed in September, showing a verdict the app stopped giving in June. There is no test that fails, no type error, no alert. The video just quietly becomes a lie.

So the one rule in our reels package is that no composition may contain a hand-typed verdict.

The engine is a dependency of the video

The reels are Remotion compositions: React components rendered to 1080x1920 at 30 fps. That means every reel is an ordinary TypeScript project in the monorepo, and it can import the same package the app imports.

// packages/reels/src/verdicts.ts
import { fitCheck } from '@munchable/rules-engine';

const cache = new Map<string, FitCheck>();

export function assess(def: ProductDef, profile: Profile): FitCheck {
  const key = `${def.id}|${JSON.stringify(profile)}`;
  let fit = cache.get(key);
  if (!fit) {
    fit = fitCheck(engineProduct(def), profile);
    cache.set(key, fit);
  }
  return fit;
}

fitCheck is the production function. It is the same call the scan endpoint makes when a real person points a real phone at a real jar. The composition passes it an illustrated product and a profile, and whatever comes back is what the card draws: the word, the colour, the icon, the named trigger underneath.

The cache is there because of how Remotion works. A 25 second reel is 750 renders of the same component tree, one per frame, and each of those renders would otherwise re-run the assessment for a product that has not changed. Memoising by product and profile turns 750 evaluations into one.

The consequence is the point. If a rule changes so that a product in a reel now scores differently, the next render of that reel shows the new verdict. We cannot ship a video that promises something the app would not say, because the video asks the app.

The cast is generic, and the ingredients are real

Every pack in a reel is an invented brand. Real packaging in a paid placement is a trademark problem, so the cast is a set of illustrated cartons, tubs and jars in our own palette, deliberately never green and never red so that nothing on a shelf reads as a verdict before the scan happens.

The ingredient lists on those invented packs are real. That is what makes the demo honest: the engine is given an ordinary ingredient list of the kind you would find on the back of an ordinary pack, and it works out the answer from there.

Which introduces the one place drift could still get in. Each illustrated product carries the ingredient ids typed by hand beside the ingredients text, and nothing in the type system stops those ids from being wrong. A typo there does not crash anything. It scores the product against a tag the engine has never heard of, quietly applies the unknown-ingredient penalty a real product would never get, and freezes the reel's verdict away from whatever the real id later comes to mean.

One test closes it:

test('every reel product is built from ids the engine knows', () => {
  const unknown: string[] = [];
  for (const [key, product] of Object.entries(PRODUCTS)) {
    for (const tag of product.ingredientsTags ?? []) {
      if (!isKnownTag(tag)) unknown.push(`${key}: ${tag}`);
    }
  }
  assert.deepEqual(unknown, []);
});

That is the whole test. It is not clever and it does not need to be. It exists so that "the cast the reels score is the cast the app would score" is a thing CI checks rather than a thing a comment claims.

The look came from a comment that promised it mirrored the app

The colours had the same disease. The reels package used to carry its own copy of the app's palette, type scale and verdict vocabulary, under a comment saying it mirrored apps/mobile/src/theme/tokens.ts. A copy maintained by a comment drifts on the first hurried afternoon. Change the caution colour, or reword the "Can't assess" label in the app, and the marketing videos keep rendering the old one with no type error anywhere in the repo.

So the platform-free half of the tokens moved into @munchable/design-tokens: the palette, the spacing and radius scales, the verdict labels and icons. The mobile app re-exports that package and adds what only React Native needs, which is the motion curve, the shadow and the font family names Expo loads. The reels import the same package and add what only a video needs, which is CSS font stacks and pixel line heights. App code still imports everything from one file, and there is now exactly one definition of what "Caution" is called and what colour it is.

Even the small print comes from the engine. The disclaimer under a result in a reel is the same exported string the app renders, so the sentence people read in a video is the sentence they will read on the screen.

Check the engine yourself

You do not have to take any of this on trust, because the same engine answers a few hundred public pages.

Does E330 cause reflux? is a page whose answer is produced by running the engine at build time, additive number and all.
The full question index is every one of those pages, and they are generated from the same source of truth as the app's result screen and the reels' result card.
The conditions we cover is the vocabulary all three surfaces share.

If you go through the index and find a page whose reasoning does not match what the app tells you on a scan, that is a bug in one deterministic function rather than a difference of opinion between a marketing team and an engineering team. That is the trade we wanted.

We wrote earlier about the same idea applied to SEO pages, in Our generated SEO pages run the production engine, and the fixture rotted. Videos turned out to be the harder case, because a page can be rebuilt on the next deploy and a published video cannot be rebuilt at all.

Twenty-eight research dossiers before a line of code, and the rule that every claim carries a URL

Daniel Pertu — Mon, 28 Sep 2026 08:23:19 +0000

CogniPrep is a practice platform for the assessments employers use when hiring. Adding support for one of them is mostly not a coding problem. It is a research problem: how long is the real test, is it adaptive, is there negative marking, what does the candidate actually see on screen, what does the employer receive at the end. Get that wrong and you have built a confident simulation of something that does not exist.

We are in the middle of adding twenty-eight of them, and the process starts with a rule that has nothing to do with code: phase one writes no code at all. One worker per provider, one markdown file each, no commits, no edits to anything else in the repository. The build contract for the round says it in those words, because the instinct when you have read enough to start is to start.

This post is about the brief those research workers get, because the same brief would work for any domain where an agent or a new team member has to establish facts you cannot personally check.

Your leads are leads, not facts

Each worker is handed a survey row: provider name, what we think their tests are, which market. The brief then undercuts it:

Your starting leads are leads, not facts. Round one found serious errors in every brief. Verify everything, and where the survey was wrong, say so in a "What the survey got wrong" section near the top.

That section is mandatory and it is the first thing in every dossier. It exists because of what happened without it: a worker who finds that the brief is wrong has a quiet incentive to build what the brief said, since that is the thing that will look correct to whoever reviews it. Making the correction a required section reverses that. A dossier whose first heading is empty now looks suspicious rather than clean.

One of the round two dossiers opens by explaining that the tests are authored by one organisation but delivered on a different vendor's platform, so the name on the candidate's invitation is never the vendor's. That distinction changes what the page has to be called, what people search for, and which of our existing providers it must not be merged into. It was not in the brief.

Every factual claim carries the URL you opened

The sourcing rule is the core of it:

Every factual claim about a test (item count, time limit, adaptive or not, negative marking, calculator, item types, interface) carries the URL you opened. Tag each as High (official or vendor), Medium (vendor marketing, reputable secondary) or Low (prep site only). Where sources disagree, record both and say which you would build to and why.

Three things that rule gets you which a plain "cite your sources" does not:

Confidence is per claim, not per document. A dossier can be High on the test structure because the organisation publishes it, and Low on item counts because nobody does. The header states both. That is a far more useful artefact than one that reads as uniformly authoritative.
Disagreement is recorded rather than resolved silently. Two prep sites saying different things about a time limit is information. Picking one and deleting the other is how a guess becomes a fact three months later.
"I opened this URL" is a different claim from "this is on the internet somewhere." It is the difference an agent will otherwise blur, and it is exactly the one that matters.

The dossiers that come back run to a thousand lines or more, with a sources index at the top where each tag resolves to a URL and a date. One worker noted that the official practice site was down for maintenance on the day, so four of the eight interfaces were Medium confidence rather than High. That sentence is worth more than any amount of polish, because it tells the build phase precisely which four screens to treat as assumptions.

Finding nothing is a valid result

The rule I would put in any research brief, in any domain:

Employers. Only associations backed by a URL you actually opened. No inference from sector norms or peers. Finding none is a valid result.

We publish pages about which employers use which assessment. The temptation to reason "this is a UK retail assessment, and these are the big UK retailers" is enormous, it produces plausible pages instantly, and it is fabrication. Every single one of those associations has to come from a page someone opened, usually the employer's own careers site describing its process.

"Finding none is a valid result" is the load-bearing sentence. Without it, a researcher who finds nothing has produced what looks like a failure, and the fix for an apparent failure is always to lower the standard of evidence. With it, an empty section is a finding.

The same applies to scope. One vendor in this round was considered and written off, and it is in the document by name as out of scope, so nobody spends a day rediscovering why.

A budget makes people choose better sources

Each research session has a cap of roughly two hundred web searches, and the brief spends it for them: prefer fetching official candidate guides, official PDFs, the vendor's own candidate FAQ and sample pages, over broad searches.

Constraining the quantity improved the quality, which I did not expect. An unbudgeted researcher searches. A budgeted one goes straight for the document that will answer ten questions at once, which is almost always the primary source. The best dossier in the round leaned on an organisation's own published transparency record for its adaptive algorithm, which no amount of searching around the subject would have matched.

What the research is for

Only then does the build contract get written, and it is written by a reviewer who has read all of the dossiers rather than by each worker for themselves. That is where overlaps get resolved: two providers that turn out to share a platform, two forces in the same country that turn out to sit the same test, a vendor whose battery is reportedly built on another vendor's and which therefore must be scheduled after it rather than beside it.

None of that is visible in the product. What is visible is that the pages are specific. Vague pages are what you write when you did not find out.

See it

cogniprep.app/games/thomas: scroll to the FAQ. The answers commit to specifics: whether the test adapts to your answers, whether every education level sits the same version, which older battery the test descends from. Each of those was a sourced line in a dossier before it was a sentence on a page.
cogniprep.app/tests: the "which test am I taking" lookup. Every row exists because someone established what the invitation email actually says, which is a research output, not a design decision.
cogniprep.app/cheating/thomas: the same research pointed at a different question. It answers with item counts taken from two published sample reports (178 and 168 items across the battery) rather than with general advice, because that is what was in the sources.

If you are briefing agents to research anything, the four sentences worth stealing are: your leads are not facts, every claim carries the URL you opened, tag the confidence per claim, and finding nothing is a valid result.

Next.js traces your imports, so the 102 files we read with fs were not deployed

Daniel Pertu — Mon, 28 Sep 2026 08:21:39 +0000

There is a class of bug that only exists in production, produces no build error, and is impossible to reproduce locally no matter how carefully you run the same command. This is one of them, and the cause is a single sentence: Next.js works out what to deploy by following your imports.

CogniPrep has a dynamic API route that serves content data. The data is a directory of JSON files, about 3.9MB across 102 of them, and the route reads one file per request with fs. It does not import them.

In next dev this is perfect. Every file in the repository is on disk, fs finds whatever it is pointed at, every request works.

In production every request 404s.

Why the files were not there

When Next.js builds a route for a serverless target, it does not ship your repository. It runs a dependency trace from the route's entry point, follows the import and require graph, and copies exactly the files that graph reaches into the function bundle. Anything the trace cannot see does not exist at runtime.

A string passed to fs.readFile is not part of an import graph. No bundler can know that a path built at runtime from a request parameter will resolve to a real file, let alone which of 102 it will be. So the route deployed with its code and none of its data, and the first request in production got an ENOENT that the handler correctly turned into a 404.

The reason to read from disk rather than import in the first place is cold starts. Importing a directory of JSON means the bundler inlines all 3.9MB into the route's JavaScript, and every cold invocation pays to parse all of it in order to answer a request that needs one file. Reading one file per request keeps the function small and the work proportional.

The fix is one key, and it should be a glob

// next.config.mjs
outputFileTracingIncludes: {
  '/api/content/[id]': ['./lib/content/data/**/*.json'],
},

Three details in that, each of which cost me a try:

The key is a route, not a file path. It is the route as Next names it internally, dynamic segment in brackets and all. Getting it wrong is silent: you get no warning that the key matched nothing, and the deploy still 404s.

The glob is relative to the project root, not to the config file or the route.

It has to be a glob, not a list. This is the part I would argue for even where a list would work today. A new data file that lands next week is included the day it is written, with no config change, and nobody has to know this trap exists to add one. Config that needs updating whenever content is added is config that will be out of date the first time somebody who did not write it adds content.

Check it without deploying

This is the part I wish I had known first, because the loop of "deploy, test, guess" is miserable.

next build writes a trace manifest next to every compiled route:

.next/server/app/api/content/[id]/route.js.nft.json

It is JSON, with a files array listing every path the tracer decided the route needs. For our route:

total traced files: 259
of those, data JSON: 102

102 is the whole directory, so the include worked. Without that config key the count is 0, and the other 259 entries, the OpenTelemetry pieces and the rest of the runtime, looked exactly the same. The manifest is where a deploy-time problem becomes a build-time check: grep it for one file you expect, and you know before you push.

It is also a good way to find the opposite problem. If a route's trace is enormous, something in its import graph is dragging a dependency you did not mean to ship, and outputFileTracingExcludes is the matching key.

The rule this generalises to

Static analysis sees imports. It does not see:

fs.readFile with a computed path
dynamic require() where the specifier is a variable
a template, locale file or dataset resolved from a request parameter
anything fetched by a worker or a child process that the bundler never visited

Every one of these works in development, because development is your whole repository sitting on a disk. Every one of these is a production-only failure, because production is a tarball someone else decided the contents of.

So when a route reads a file at runtime, the include belongs in the same commit as the read. Not after the first 404.

See it

cogniprep.app/games lists the practice tests. Sign in, start one, and keep the Network tab open: the content for that test arrives in a single request after the page, rather than being baked into the page bundle. That request is the route this whole post is about, and the file it reads was invisible to the build until the config key above existed.
On your own project: run next build, then open any .nft.json under .next/server/app/ and read the files array. It is the most direct answer available to "what actually gets deployed", and most people never look at it.

Our preload header downloads four files the page never uses, and one query parameter is why

Daniel Pertu — Mon, 28 Sep 2026 08:19:57 +0000

CogniPrep's homepage shows a grid of company logos. The first four are above the fold, so next.config.mjs sends a preload hint in a response header, which is the earliest possible moment to start those downloads: before the browser has parsed a single byte of HTML.

{
  source: '/',
  headers: [
    {
      key: 'Link',
      value: [
        '</logos/hsbc.svg>; rel=preload; as=image',
        '</logos/barclays.svg>; rel=preload; as=image',
        '</logos/lloyds.svg>; rel=preload; as=image',
        '</logos/santander.svg>; rel=preload; as=image',
      ].join(', '),
    },
  ],
}

That header is live right now. It also downloads four files the page then ignores, and I only found out because I opened the Network tab to take a screenshot for a different post.

What the waterfall actually says

Homepage, cache disabled, resources filtered to /logos/:

Request	Started	Transferred
`hsbc.svg`	77ms	1,253 B
`barclays.svg`	77ms	3,186 B
`lloyds.svg`	77ms	3,971 B
`santander.svg`	77ms	1,207 B
`hsbc.svg?dpl=dpl_26dq...`	83ms	1,253 B
`barclays.svg?dpl=dpl_26dq...`	83ms	3,186 B
`lloyds.svg?dpl=dpl_26dq...`	83ms	3,971 B
`santander.svg?dpl=dpl_26dq...`	83ms	1,207 B

Every one of those four logos is fetched twice, six milliseconds apart, with identical byte counts. The preloaded copies are the ones without the query string, and nothing on the page ever asks for them.

9,617 bytes, on every cold load, at the very front of the queue where they are competing for connections with the resources that actually paint the page.

The query parameter is not ours

?dpl=dpl_26dqywkfvSxFuivR2MTB3eRMvsVb is Vercel's deployment id. The platform appends it to static asset URLs so that a client which has already loaded an older build cannot silently mix its assets with a newer one. It is a good feature. It is also applied to the URLs the framework emits, and not to a Link header you hand-wrote in next.config.mjs.

A preload is matched by URL, and the query string is part of the URL. /logos/hsbc.svg and /logos/hsbc.svg?dpl=dpl_26dq... are two different resources as far as the preload cache is concerned. So the browser dutifully fetches the first, then the page asks for the second, and the first sits in the cache until it is evicted, having helped nobody.

The same trap is waiting behind anything that rewrites asset URLs between your config and your markup: content hashes, a CDN's cache-busting parameter, an image optimiser that serves /_next/image?url=..., an assetPrefix. If the preload hint is written by hand and the request is generated by a pipeline, they will drift, and the only symptom is a duplicate row in a waterfall nobody is looking at.

Chrome was telling us the whole time

The console on a cold load has this, four times:

The resource https://cogniprep.app/logos/hsbc.svg was preloaded using link preload
but not used within a few seconds from the window's load event. Please make sure it
has an appropriate `as` value and it is preloaded intentionally.

That warning is normally read as "you preloaded something you did not need". It also fires in the more annoying case, which is this one: you preloaded something you did need, under a URL the page never requested. Same message, entirely different fix. Worth remembering, because the instinctive response to that warning is to delete the preload, and here the preload was pointing at the right file.

The framework was already doing it properly

The grid is a next/image per logo with the first two rows eager and the first row at high priority:

<Image
  src={company.logo}
  alt={`${company.name} logo`}
  fill
  loading={index < 8 ? 'eager' : 'lazy'}
  fetchPriority={index < 4 ? 'high' : 'auto'}
/>

Next.js emits in-document preload links for those eager images, and its links carry the deployment id because the framework is what generates asset URLs in the first place. In the waterfall above, that is what the eight ?dpl= requests at 83ms are: four for the header's logos and four more for the second row, none of them duplicated.

So the header is not just mismatched, it is redundant. The fix is to delete it and let the eager or priority props on the images do the work, which keeps one system in charge of asset URLs. The alternative, building the header at deploy time from the same deployment id, means teaching a config file about a platform environment variable in order to duplicate a thing the framework already emits correctly. That is a worse trade.

Six milliseconds of head start is not worth owning a second URL scheme.

See it

You can check every claim in this post from outside:

Open cogniprep.app in DevTools, Network tab, Disable cache ticked, then reload and filter for logos. Count the hsbc.svg rows. There are two.
Compare their start times. The bare pair arrives first, ahead of the HTML's own preload links, which is the header doing exactly what it was asked to do with the wrong URL.
Open the Console on that same load and read the four preload warnings, one per logo.
Look at the response headers for the document itself. The link: header is right there, listing the four URLs without the query.

And the general lesson, which is the only reason this is worth a post: a preload hint is a string match against a URL, not a promise about a file. If any layer of your stack rewrites asset URLs after you write the hint, your preloads are not early, they are extra. The check takes thirty seconds and it is the one where I would not trust the config file.

Nine analytics defaults we turned off, and the one that has to be decided in the browser

Daniel Pertu — Mon, 28 Sep 2026 08:16:26 +0000

An analytics SDK arrives with its defaults set to "collect everything". That is the right default for the vendor and almost never the right one for the page, because every option is spending one of three budgets: bytes downloaded, requests made, or rows stored. CogniPrep's posthog.init call is mostly a list of things switched off, and one decision that is only correct because it is made in the browser rather than in the vendor dashboard.

First, it is not their domain

The client points at our own origin:

posthog.init(key, {
  // Reverse proxy (see `rewrites` in next.config.mjs) so ad blockers do not
  // silently erase a chunk of the numbers.
  api_host: '/ingest',
  ui_host: host,
  ...
});

api_host is where events go. ui_host stays the real PostHog host, because that is what the SDK uses when it needs to link a human back to the dashboard. Get that pair the wrong way round and your toolbar links point at your own marketing site.

The proxy itself is three rewrites, and the comment on them is load bearing:

async rewrites() {
  return [
    // PostHog reverse proxy - order matters!
    {
      source: '/ingest/static/:path*',
      destination: 'https://us-assets.i.posthog.com/static/:path*',
    },
    {
      source: '/ingest/decide',
      destination: 'https://us.i.posthog.com/decide',
    },
    {
      source: '/ingest/:path*',
      destination: 'https://us.i.posthog.com/:path*',
    },
  ];
}

Next.js matches rewrites in order and stops at the first hit, so the catch-all has to be last. PostHog serves its static assets from a different host to its ingestion API, us-assets.i.posthog.com rather than us.i.posthog.com, so if the generic /ingest/:path* rule sits first it swallows /ingest/static/... and sends the library's own script requests to the ingestion endpoint. You do not get an error for that. You get an analytics client that never finishes loading, on some visits, depending on which files it needed.

This is the whole reason I am wary of "order matters!" comments that do not say which order or why. That one now does.

Sampling replay on the server samples the wrong thing

The one genuinely interesting decision in the file:

const SESSION_RECORDING_SAMPLE_RATE = 0.1;
...
const shouldRecord = Math.random() < SESSION_RECORDING_SAMPLE_RATE;
...
// `disable_session_recording: true` prevents the recorder chunk from being
// fetched at all, which is why the sampling decision is made above.
disable_session_recording: !shouldRecord,

PostHog can sample session replay for you in project settings. That setting decides whether a recording is kept. The rrweb recorder is still downloaded, still initialised, and still runs on every visitor whose recording will be thrown away. It is the single largest analytics cost on the page.

Deciding in the browser, before the library is configured, means nine out of ten sessions never fetch the recorder at all. The recordings stay useful at that rate because of what they are for: watching how a flow actually goes, not auditing one named user. When a specific user's session matters, Sentry's on-error replay already covers it.

The general shape here is worth stealing even if you never touch PostHog. A server-side sampling rate is a storage optimisation. A client-side one is a performance optimisation. They have the same name and they are not the same thing.

The list of noes

// Anonymous visitors are counted but get no person record.
person_profiles: 'identified_only',

// Autocapture fired an event on every click and produced `$autocapture` rows
// keyed by DOM position that nobody ever built an insight on.
autocapture: false,
capture_heatmaps: false,

// Web vitals are the honest measure of the latency users feel, and cheap.
// Network timing records a payload per request for detail we never needed.
capture_performance: { web_vitals: true, network_timing: false },

// Errors belong in Sentry, which has the stacks, releases and grouping.
capture_exceptions: false,

// localStorage only. The default is 'localStorage+cookie'.
persistence: 'localStorage',

Each of those has a sentence attached in the source, because "we turned it off" without a reason is how a setting gets turned back on in eighteen months by someone who assumes it was an accident.

Two are worth expanding.

Autocapture off costs you heatmaps. That is a real trade, not a free win, and it should be written down next to the flag rather than discovered later. The bet is that a small number of named events beats a large number of DOM-position events that nobody queries.

persistence: 'localStorage' is not a performance choice, it is a consistency one. The default is localStorage+cookie, which sets a cookie, and our published cookie policy says analytics identifiers live in local storage. A config default that quietly contradicts your own policy page is the kind of thing that is true for a year before anyone opens DevTools. localStorage alone still recognises a returning visitor, so nothing analytically useful is given up.

There is one default still on that I have not earned yet: the surveys script loads, and we run no surveys. That one is on the list.

None of it starts until the page is idle

The loader is an import() scheduled at the first idle moment, with a Safari fallback, because Safari still has no requestIdleCallback:

useEffect(() => {
  if (typeof window.requestIdleCallback === 'function') {
    const handle = window.requestIdleCallback(() => loadPostHog(), { timeout: 4000 });
    return () => window.cancelIdleCallback?.(handle);
  }
  const timer = setTimeout(loadPostHog, 1500);
  return () => clearTimeout(timer);
}, []);

Nothing is lost by starting late. capture_pageview: 'history_change' records the initial view whenever init happens, and the thin client module queues anything fired before the library lands. The failure path is a .catch that does nothing on purpose: blocked, offline or a failed chunk all mean the queued events are never sent and the page carries on.

The component also renders no context provider. posthog-js/react exists for the usePostHog and feature flag hooks, this app uses neither, so importing it would be bundle weight in exchange for nothing.

See it

Open cogniprep.app with DevTools on the Network tab and filter for ingest. You will see config.js, web-vitals-with-attribution.js, surveys.js and an event POST, every one of them on cogniprep.app. Now filter for posthog.com: nothing. That is the reverse proxy working.
Note the timings. On my last load the first /ingest request started about 170ms after navigation, well after the page had painted.
Application, Local Storage, ph_<project key>_posthog. Then read cogniprep.app/cookies, which describes that same key in the local storage section. The policy and the config are meant to agree, and this is the check that they do.
Reload a handful of times and watch for a recorder chunk in the Network tab. Most loads will not have one, which is the client-side sample rate you are watching from the outside.

Our PWA plugin never emitted a service worker, and Turbopack is the reason

Daniel Pertu — Mon, 28 Sep 2026 08:15:03 +0000

CogniPrep's next.config.mjs used to export its config through a PWA wrapper, @ducanh2912/next-pwa, configured with two options:

cacheOnFrontEndNav
aggressiveFrontEndNavCaching

Both read as "client side navigation is faster now". Neither did anything, and had not for as long as anyone could check.

next-pwa and its forks work by injecting a webpack plugin, which is the thing that runs Workbox and writes sw.js into your output. next build on this project compiles with Turbopack, so that plugin was never instantiated. No error. No warning. The build succeeded every time, and the config kept sitting at the top of the file looking like a feature.

Next.js 16 is where most people will meet this, because Turbopack is the default builder there rather than a flag you opt into. If your project carried a webpack-plugin-shaped dependency across that upgrade, it is worth checking whether it is still doing its job, because the failure mode is silence.

How to prove it is dead rather than assuming

The check that settled it took a minute:

public/sw.js does not exist in the working tree.
No service worker exists in the build output.
git log has never contained one.
On the deployed site, https://cogniprep.app/sw.js returns 404.
In the browser, await navigator.serviceWorker.getRegistrations() returns [].

Point 5 is the one I would start with on any site you have inherited. Paste it into the console of the production page. If the array is empty and your config says you have a PWA, your config is a comment.

What replaced the wrapper in our repo is a comment explaining the hole, which is the only honest thing to leave behind:

// REMOVED: @ducanh2912/next-pwa.
//
// It was configured with `cacheOnFrontEndNav` and `aggressiveFrontEndNavCaching`,
// which read as an attempt to make client-side navigation faster. It never did
// anything. The plugin works by injecting a webpack plugin, and `next build`
// compiles this project with Turbopack, so no service worker was ever emitted.
//
// Dead configuration that looks like a performance feature is worse than none,
// because it stops anyone from asking why navigation is slow.

Dead config is worse than no config for exactly that reason. As long as the file says "aggressive navigation caching", nobody profiles navigation. The line was an answer to a question that had never been asked properly.

The half we do ship

What survived is the manifest, which in the App Router is a TypeScript file rather than a static asset:

import type { MetadataRoute } from 'next';

export default function manifest(): MetadataRoute.Manifest {
  return {
    name: 'CogniPrep - Arctic Shores Practice',
    short_name: 'CogniPrep',
    description: 'Practice all 14 Arctic Shores psychometric games and AI mock video interviews.',
    start_url: '/',
    display: 'standalone',
    background_color: '#000000',
    theme_color: '#000000',
    orientation: 'portrait',
    icons: [
      { src: '/logo-light.png', sizes: '512x512', type: 'image/png', purpose: 'any' },
      { src: '/logo-light.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' },
    ],
  };
}

Next serves that at /manifest.webmanifest and injects the <link rel="manifest"> tag into every page for you. There is no <link> anywhere in our layout; the file's existence is the wiring.

That gets you the metadata half of a progressive web app: the name and icon a phone uses when someone saves the page to their home screen, the theme colour the browser paints its chrome with, and the standalone display mode that hides the URL bar once the app is installed. It gets you none of the offline half, because offline is entirely a service worker concern.

Being clear about which half you have matters, because a manifest is the part that makes a site look installable in an audit tool while the behaviour people actually associate with a PWA, working on the train, is missing.

Two things in that manifest are still wrong

Writing this post is what made me read the object properly, which is the usual outcome of explaining your own config to strangers.

Both icons are the same file. One entry is purpose: 'any', the other is purpose: 'maskable', and they point at the same 512 square PNG. Maskable icons are not a flag you set on an existing asset. The platform crops them to whatever shape it likes, a circle, a squircle, a rounded square, and only the middle 80% is guaranteed to survive. A maskable entry needs to be a separate export with the mark shrunk inside that safe zone. Declaring it on the standard icon means Android is free to shave the edges off our logo.

There is no 192 pixel icon. The conventional set is 192 and 512. Shipping only one size leaves the smaller slots to be produced by downscaling, which is exactly where a detailed mark goes muddy.

Neither is a crisis, because nobody can install the thing as an offline app today anyway. Both are on the list for when a Turbopack-compatible service worker, Serwist is the usual successor, is actually worth doing.

See it

cogniprep.app/manifest.webmanifest: the live output of that TypeScript function. Note the two identical icon entries.
cogniprep.app/sw.js: 404, which is the whole post in one request.
Open cogniprep.app, then DevTools, Application, Service Workers. The list is empty. Compare with Application, Manifest, which is fully populated. That gap is the shape of a half-built PWA and it is very common.
View source and search for rel="manifest". It is there, and it is not in our source code.

The lesson I took from it is narrower than "audit your dependencies". It is that a build plugin which no longer runs produces the same successful build as one that does, so migrating bundlers needs an output check per plugin, not a green build.

Our health endpoint is public, so it answers with a count instead of a name

Daniel Pertu — Mon, 28 Sep 2026 08:06:15 +0000

CogniPrep has a health check at /api/health. It has no authentication, no rate limit and no secret query parameter. That is deliberate: an uptime monitor that needs credentials is a thing you turn off during an incident, which is the exact moment you wanted it.

Open it right now:

https://cogniprep.app/api/health

Today it says this:

{
  "status": "healthy",
  "timestamp": "2026-09-28T08:04:00.782Z",
  "checks": {
    "database": { "status": "healthy", "responseTime": 67 },
    "redis": { "status": "configured" },
    "environment": { "status": "healthy" },
    "monitoring": { "status": "configured" }
  }
}

Four statuses and one number. That is the whole payload, and the interesting part is everything that is not in it.

A public endpoint is a reconnaissance surface

The useful debugging information in a health check is exactly the information you would want if you were probing someone else's stack. Two places in this route had to be written twice because the first version was helpful to the wrong audience.

The first is the database check. A failed query has an error message attached, and postgres driver errors are chatty: host names, role names, pooler internals, sometimes a truncated statement.

} catch (error) {
  // Log the detail for us; return only the status to the caller. Database error
  // messages can disclose host names, roles and driver internals.
  logError('[health] Database check failed', error);
  checks.database = { status: 'unhealthy' };
  isHealthy = false;
}

The detail still exists. It goes to the logger, which goes to Sentry, which is where the person fixing it is looking anyway. The caller gets one word.

The second is the environment check, and it is the one I would have got wrong by default:

const requiredEnvVars = [
  'DATABASE_URL',
  'STRIPE_SECRET_KEY',
  'STRIPE_WEBHOOK_SECRET',
  'CRON_SECRET',
];
const missingEnvVars = requiredEnvVars.filter((v) => !process.env[v]);
// Report only the count. Naming the missing variables tells an anonymous caller
// exactly which part of our configuration is absent, e.g. that
// STRIPE_WEBHOOK_SECRET is unset, which implies webhook verification is broken.
checks.environment = {
  status: missingEnvVars.length === 0 ? 'healthy' : 'unhealthy',
  missingCount: missingEnvVars.length > 0 ? missingEnvVars.length : undefined,
};

{"missingCount": 1} tells an operator to go and look at the deploy. {"missing": ["STRIPE_WEBHOOK_SECRET"]} tells a stranger that our webhook signature verification is currently unenforced, which is an invitation to post a fake checkout.session.completed at us. The names go to the log line, not the response body.

Same reasoning for Redis and Sentry: the response says configured or not_configured, never a URL, never a project, never a DSN.

Degraded is not down

The database check times itself and grades the result:

const dbResponseTime = Date.now() - dbStart;
checks.database = {
  status: dbResponseTime > 1000 ? 'degraded' : 'healthy',
  responseTime: dbResponseTime,
};

degraded still returns HTTP 200. Only a real failure, a thrown query or a missing required variable, returns 503.

That split exists because a monitor that pages on slowness gets muted, and a muted monitor does not page on outages either. A one second query on a pooled Postgres connection that has just cold started is not an outage, it is a Monday. The number is published so a human can watch it drift; the status code is reserved for "a thing is actually broken".

responseTime is the one piece of internal telemetry the endpoint does hand out. It is a duration with no identifiers attached, and it is the single most useful thing to have in a screenshot when someone reports that the site feels slow.

The five second timer that has to be cleared

The database check is a race, because a hanging connection should fail the check rather than hang the function until the platform kills it:

let dbTimeout: ReturnType<typeof setTimeout> | undefined;
try {
  // The timer is cleared in `finally` - otherwise a fast query still leaves a
  // pending 5s timeout holding the serverless function open.
  await Promise.race([
    db.execute('SELECT 1'),
    new Promise((_, reject) => {
      dbTimeout = setTimeout(() => reject(new Error('Database timeout')), 5000);
    }),
  ]);
  ...
} finally {
  if (dbTimeout) clearTimeout(dbTimeout);
}

Promise.race settles as soon as the first promise settles, but it does not cancel the loser. When the query comes back in 67ms, that setTimeout is still armed. On a serverless runtime the invocation does not finish while a timer is pending, so a 67ms health check bills like a five second one, every single time the monitor calls it. At one call a minute that is a quiet, permanent, entirely self-inflicted cost.

clearTimeout in a finally is four lines. It is also the difference between a health check that costs nothing and one that is the most expensive route in the app.

It must never be cached

The last trap is framework shaped. Next.js will happily prerender a route handler that looks static, and a cached health check is worse than no health check: it reports the state of the world at build time, with a timestamp that makes it look live.

export const dynamic = 'force-dynamic';
export const revalidate = 0;

and on the response:

headers: { 'Cache-Control': 'no-cache, no-store, must-revalidate' }

Both are needed. The route segment config stops the framework and the CDN caching it; the response header stops everything between us and the monitor doing the same.

See it

cogniprep.app/api/health: the live response. Count the fields. There is no host, no version, no library, no region, no variable name.
Open it in DevTools and look at the response headers: cache-control: no-cache, no-store, must-revalidate, and no x-vercel-cache: HIT no matter how many times you reload.
Reload it a few times and watch checks.database.responseTime move. That number is the check doing real work rather than reading a cached answer.

The general rule I would now apply to any unauthenticated status route: every field has to justify itself to an audience of strangers. Statuses, durations and counts pass. Names, hosts, versions and error strings go to the log.

Our OG card is a Playwright screenshot, and the Chromium comes from the workspace next door

Daniel Pertu — Sun, 27 Sep 2026 15:41:54 +0000

The social card for Notifio is a PNG at /og-image.png, and it is produced by taking a Playwright screenshot of a string of HTML at build time.

That is the second answer I have given to this problem. Another app in the same family renders its card with next/og, from the same logo SVG, font files and palette the site itself uses, which I wrote up in our link preview cards are drawn by code, from the same three files as the site. I still think that is the right call there. Here I deliberately did the opposite, and the reasons are all about where the render happens rather than about which renderer draws nicer text.

/**
 * It is a build-time script, not a route. `next/og` would put a satori render on
 * the request path and cannot read the woff2 files the app already ships, and an
 * OG card that changes once a quarter has no business being computed per
 * request. Playwright comes from the desktop app workspace, which already
 * depends on it and already has a Chromium downloaded, so the server package
 * takes on no new dependency for a script that runs by hand.
 *
 * Run from server/:  node scripts/generate-og-image.mjs
 */

Borrowing a browser from the workspace next door

Notifio is a repository with two halves: a marketing site in server/, and the Electron desktop app in app/. The app drives a real browser, so it already depends on Playwright and, because it ships Chromium inside the packaged app, it already has one downloaded on disk. I wrote about that bundling in shipping Playwright's Chromium inside a packaged Electron app.

So the script reaches sideways rather than adding a dependency:

const HERE = dirname(fileURLToPath(import.meta.url));
const APP = join(HERE, "../../app");

// Set before playwright is imported: it reads the browsers path at module load.
process.env.PLAYWRIGHT_BROWSERS_PATH ??= join(APP, "playwright-browsers");
const { chromium } = await import(join(APP, "node_modules/playwright/index.mjs"));

Three details in four lines, and two of them are things I got wrong first.

The dynamic import is load-bearing. PLAYWRIGHT_BROWSERS_PATH is read when the Playwright module initialises, not when you call launch(). A static import { chromium } from "playwright" is hoisted above the assignment, so the environment variable would be set after the value it is meant to influence has already been read, and the launch would go looking in the default cache. await import() puts the import back in statement order. That only works at the top level because this is a .mjs with top-level await available, which is one of the better arguments for writing repo scripts as ESM.

If you have ever been confused about why setting an env var in your script had no effect on a library, this is usually the shape of it: the library read it during module initialisation and your assignment ran after the import.

??= rather than =. An explicitly provided PLAYWRIGHT_BROWSERS_PATH still wins, which matters on a machine where the app workspace has not been installed.

The channel has to be named. This one cost me a genuinely confusing ten minutes:

// `channel: "chromium"` picks the full browser the app workspace ships. The
// default would reach for chrome-headless-shell, which that workspace has no
// reason to download and therefore does not have.
const browser = await chromium.launch({ channel: "chromium" });

Recent Playwright versions default chromium.launch() to chrome-headless-shell, a separate and smaller download. The desktop app needs a full browser and only installs that, so the default asks for an executable that is not in the directory even though the directory clearly contains a Chromium. The error reads like a corrupt install rather than a wrong channel.

The fonts are the actual reason this is not next/og

The card uses three typefaces, and they arrive by two different routes. Geist Mono comes out of node_modules and gets inlined:

/** Inlined so Chromium never has to resolve a file:// URL for them. */
const monoFont = (weight, file) => {
  const path = join(SERVER, "node_modules/geist/dist/fonts/geist-mono", file);
  const b64 = readFileSync(path).toString("base64");
  return `@font-face{font-family:'Geist Mono';font-weight:${weight};font-style:normal;src:url(data:font/woff2;base64,${b64}) format('woff2');}`;
};

page.setContent() gives the page an about:blank-ish origin, from which relative and file:// font URLs are a fight you do not need to have. Base64 in a data URL is bigger and completely reliable, and the file is thrown away thirty milliseconds later anyway.

The other two come from Google Fonts with an ordinary <link>, because the site loads them the same way through next/font/google. That is why the screenshot waits on the network:

await page.setContent(html, { waitUntil: "networkidle" });
await page.evaluate(() => document.fonts.ready);
await page.screenshot({ path: OUT, type: "png" });

That middle line is the one I would put on a poster. networkidle tells you the requests finished. It does not tell you the font has been applied and the text re-laid-out, so a screenshot taken immediately after can catch the fallback face, with the wrong metrics and the wrong weight, in a 1200x630 image that you then ship to every social platform on the internet. It fails in the ugliest possible way: it looks fine locally when the font is warm in the HTTP cache, and wrong on a cold machine.

document.fonts.ready is a promise that resolves when font loading and layout have settled. It is two words and it is the difference between a card that is correct and a card that is correct on your laptop.

The 2x asset with a 1x declaration

The render is 1200x630 logical pixels at double density:

const page = await browser.newPage({
  viewport: { width: WIDTH, height: HEIGHT },
  deviceScaleFactor: 2,
});

The file on disk is therefore 2400x1260 and about 215KB. The metadata still declares the logical size:

images: [{ url: "/og-image.png", width: 1200, height: 630, alt: "Notifio" }],

That is not an inconsistency, it is the point. og:image:width and og:image:height describe the aspect and layout the consumer should reserve; the bitmap is allowed to be denser than that. A link preview in Slack or iMessage on a retina screen renders the card at a good physical size, and a 1x PNG of text at 74px looks soft in exactly the place where the card is doing its job.

You can check the numbers yourself without downloading anything much:

# The PNG header carries the real dimensions in bytes 16..24.
python3 -c "import struct;d=open('og-image.png','rb').read();print(struct.unpack('>II',d[16:24]))"
# (2400, 1260)

The honest cost

The next/og version of this in my other app cannot drift from the site, because it literally imports the site's three inputs. This one is weaker, and the weakness is in the CSS:

/* The same 40px grid the homepage CTA section lays over its background. */
.grid{
  position:absolute;inset:0;opacity:0.03;
  background-image:
    linear-gradient(rgba(255,255,255,1) 1px, transparent 1px),
    linear-gradient(90deg, rgba(255,255,255,1) 1px, transparent 1px);
  background-size:40px 40px;
}

"The same 40px grid" is a claim in a comment, not a shared constant. The fonts genuinely cannot drift, because the script reads the same woff2 files the site serves, and the logo cannot drift because it reads public/icon-light.svg. But the palette and the grid are a copy, and if I restyle the homepage this file will not notice.

I decided that was acceptable for a card that changes about once a quarter, and I would decide differently for anything rendered per-request or per-page. It is a real trade and I would rather write it down than pretend the script is more principled than it is.

The pills at the bottom of the card have the same problem in a more dangerous form, since they quote a price:

<div class="pill">&pound;20 one-time</div>
<div class="pill">macOS &amp; Windows</div>
<div class="pill">No subscription</div>

Everywhere else on the site, that number is derived from the constant Stripe charges, so the pricing page and the structured data cannot disagree with the invoice. In this file it is typed out. A build-time script that reads LICENSE_PRICE_PENCE would have been three lines, and the only reason it does not is that the script predates my caring about it. That is a genuine bug waiting for a price change, and writing this paragraph is how I noticed.

The rule I took away

The question was never "satori or Chromium". It was "what is this code allowed to depend on". A request-time renderer can only use what is in the serverless bundle, which rules out reading font binaries off disk and rules out launching a browser. A build-time script can use anything on the machine, including a browser that a sibling workspace downloaded for a completely different reason.

Deciding where the render happens first, and then picking the tool, got me to a simpler answer than starting from the tool. And it is why the same problem has two different answers in two of my apps without either of them being wrong.

Our deploy CLI default origin is the one origin that can never work

Daniel Pertu — Sun, 27 Sep 2026 15:38:11 +0000

The marketing site for Notifio has a few hundred pages, most of them generated from data: one per rental site under /alerts, one per competitor under /compare, plus the guides at /guides. After a deploy that changes any of them, a script tells IndexNow, so Bing, Yandex, Seznam and Naver re-crawl the changed pages instead of waiting for their own schedule.

I have written about the protocol's traps before, in a 200 from IndexNow does not mean it read your key, and about only pinging pages that actually changed in IndexNow, but only when the page actually changed.

This post is about something else entirely: the script has five separate ways to refuse to run, and writing them turned out to be most of the work. Not the HTTP call. The refusals.

The default is the one value that can never work

Here is the default origin, resolved the obvious way:

site: process.env.NEXT_PUBLIC_APP_URL ?? DEFAULT_SITE,

NEXT_PUBLIC_APP_URL is http://localhost:3001. It says so in .env, because that is what the Next dev server binds to and every other consumer of that variable wants exactly that.

So the default origin for this command, in the environment where I will actually be typing the command, is a host the search engines cannot reach. IndexNow works by having the engine fetch a key file from your domain over the public internet. Point it at localhost and there is no version of the request that can succeed.

Without a guard, that failure arrives as a fetch failed on the key file check, which reads like a network problem and sends you off to look at your connection. The guard says the actual thing:

/**
 * The engines have to fetch the key file over the public internet, so a local
 * origin can never work. NEXT_PUBLIC_APP_URL is localhost in development, which
 * makes this the likeliest way to run the command wrongly.
 */
if (!isPublicHost(host)) {
  die(
    `${opts.site} is not a publicly reachable origin, so the engines could never fetch the key file.\n` +
      `  Pass the live origin explicitly, for example: pnpm indexnow --site ${DEFAULT_SITE} ...`,
  );
}

The thing I would not have predicted is how much of the module that one check justifies. isPublicHost is not a URL validator, it is specifically a "could a stranger's server reach this" test, and that means enumerating the private ranges:

export function isPublicHost(host: string): boolean {
  const hostname = host.replace(/:\d+$/, "").toLowerCase();

  if (hostname === "localhost" || hostname.endsWith(".localhost")) return false;
  if (hostname === "::1" || hostname === "[::1]") return false;
  if (hostname.endsWith(".local") || hostname.endsWith(".internal")) return false;

  // Private and loopback IPv4 ranges, per RFC 1918 and RFC 5735.
  const ipv4 = hostname.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
  if (ipv4) {
    const [a, b] = ipv4.slice(1, 3).map(Number);
    if (a === 127 || a === 10 || a === 0) return false;
    if (a === 192 && b === 168) return false;
    if (a === 172 && b >= 16 && b <= 31) return false;
    if (a === 169 && b === 254) return false;
    return true;
  }

  // A bare name with no dot cannot be a registrable domain.
  return hostname.includes(".");
}

Twenty lines to catch a mistake that costs thirty seconds of confusion. Worth it, and it earned its keep a second time in a place I did not write it for. The --init subcommand generates a key and then tells you where to go and confirm it, and that instruction is useless if it points at localhost:

// On a dev .env the origin is localhost, which is useless in the "now go
// confirm this URL" line, so fall back to the production site for display.
const display = isPublicHost(new URL(origin).host) ? origin : DEFAULT_SITE;

The general point: if your command's default comes from the environment, check whether the environment you will be typing it in supplies a value that works. Config inherited from a dev server is usually right for the dev server and wrong for anything that talks to the outside world. This is not defensive programming, it is the difference between a tool being usable and being a thing you have to remember a flag for.

When the remote is all-or-nothing, partial success is a lie

The protocol requires every URL in a submission to belong to the host you name in the payload, and a single foreign URL causes the engine to reject the whole batch. Not to skip that URL. To reject the request.

That fact decides the behaviour of the client, and the library's own header says why the filtering has to happen before the request rather than after:

/**
 *  - Every URL in one request must live on the same host as `host`, and the
 *    whole request is rejected if any single URL does not. Filtering therefore
 *    has to happen before submitting, not after a 422 comes back.
 */

The interesting decision is what the CLI does with a stray. It could drop it and submit the rest. It does not:

const { onHost, offHost } = partitionByHost(resolved, host);
if (offHost.length > 0) {
  // A single foreign URL makes the engines reject the entire batch, so this is
  // fatal rather than a warning: submitting the remainder silently would hide a
  // mistyped hostname behind a successful-looking run.
  die(`These URLs are not on ${host}:\n  ${offHost.join("\n  ")}`);
}

A mistyped hostname in the argument list is almost always a page I meant to submit. Filtering it out and printing a tick would mean the run "succeeded" while the page I cared about was never announced, and I would not find out for weeks. The library still returns the strays rather than discarding them, for the same reason: they are evidence, not noise.

Compare that with what is right next to it, which is deliberately not fatal:

const unique = [...new Set(onHost)];
if (unique.length < onHost.length) {
  const dropped = onHost.length - unique.length;
  console.log(`• Removed ${dropped} duplicate ${dropped === 1 ? "URL" : "URLs"}`);
}

Duplicates are untidy. Off-host URLs are a rejection. The test I ended up applying to every input problem: would the remote refuse this, or is it merely inelegant? Refusal is fatal, inelegance is a note.

Check the thing that fails invisibly

A wrong key does not produce a helpful error. It produces a 403 with no body, and nothing on your site looks broken, so the failure mode is "pages quietly stopped being re-crawled by everything except Google". That is why the submission is preceded by a fetch of your own key file:

/**
 * Confirms the hosted key file exists and matches the key being submitted.
 *
 * Worth doing before every run: a key mismatch is the single most common way
 * this integration breaks, and it fails as a 403 on the submission itself,
 * which is far harder to read than "the file at this URL says something else".
 */

And the check reports the mismatch in the most boring, most useful way available, by quoting what it found:

const body = (await response.text().catch(() => "")).trim();
if (body !== key) {
  const preview = body.length > 60 ? `${body.slice(0, 60)}...` : body || "(empty)";
  return { ok: false, url, message: `contains ${preview}, expected ${key}` };
}

The refusal that follows tells you the consequence and the escape hatch in two lines:

die(
  `Key file ${check.url} ${check.message}.\n` +
    "  Every submission will 403 until it matches. Fix it, or pass --skip-verify to submit anyway.",
);

Naming the escape hatch in the error message matters more than it sounds. A guard with no documented way past it is a guard somebody will eventually delete, because the one time it is wrong they will be in a hurry. --skip-verify exists so that the answer to "the check is wrong and I need to ship" is a flag rather than a commit.

Refuse the ambiguous invocation instead of guessing

Two flavours of this, and neither is clever:

if (opts.sitemap && opts.urls.length > 0) {
  die("Pass either --sitemap or an explicit list of URLs, not both.");
}
if (!opts.sitemap && opts.urls.length === 0) {
  die("Nothing to submit. Pass one or more URLs, or --sitemap.");
}

--sitemap with extra URLs could plausibly mean "the sitemap plus these", so it could have been a union. I made it an error because I cannot tell which of the two the person typing it meant, and a tool that guesses at intent in a command that talks to four search engines is a tool that will one day submit 235 URLs when you meant three.

The empty case is the same principle from the other side. Zero URLs is not a successful run of nothing, it is an invocation that did not say what it wanted.

Unknown engines get the same treatment, with the valid set in the message so you do not have to go and read the source:

if (!Object.hasOwn(INDEXNOW_ENDPOINTS, opts.engine)) {
  die(`Unknown engine: ${opts.engine}. Expected one of ${Object.keys(INDEXNOW_ENDPOINTS).join(", ")}.`);
}

Object.hasOwn rather than in or a truthiness check, so --engine constructor is an unknown engine rather than a crash.

Exit immediately, or exit at the end

There are two ways this script can fail, and they use different mechanisms on purpose.

Everything above is die(), which prints and calls process.exit(1) straight away. Nothing has been sent at that point, so there is nothing to finish and no reason to continue.

Once the submission loop starts, it switches:

let failed = 0;
for (const [index, batch] of batches.entries()) {
  ...
  if (!result.meaning.ok) failed++;
}

if (failed > 0) {
  console.error(`✗ ${failed} of ${batches.length} batches failed`);
  process.exitCode = 1;
}

A failed batch does not abort the run, because the other batches are independent and half a submission is better than none. And the exit status is set rather than taken, so the pending output flushes before the process leaves.

That split is worth adopting as a habit. process.exit while you still have work or unflushed output is how you lose the line you needed; process.exitCode while you are validating arguments is how you accidentally continue into the thing you just decided not to do.

The refusal that is only a comment

One thing the script does not enforce, and I went back and forth on it. The docblock says:

 * Submitting the same URL repeatedly with no change to the page is the one
 * documented way to get throttled, so prefer passing the handful of pages a
 * deploy actually touched over running --sitemap out of habit.

--sitemap exists and pulls every URL out of the live sitemap.xml, which for this site is a few hundred pages. Running it after every deploy would be the easy habit and the wrong one.

I could have made the script refuse --sitemap unless some page actually changed, and there is a separate mechanism that answers that question. But putting that logic here would mean this command needed to know about build output and content hashes, which is a lot of coupling for a script whose job is one POST. So it stays a sentence in the usage text, and the enforcement lives where it belongs.

Not every rule you want should be a guard. The ones worth building are the ones where the mistake is silent, and "I submitted too many URLs" is not silent, it is throttling with a 429 and a documented cause. The five refusals above all exist because their failures were invisible.