A shared function inherits the scars

There is a rule everyone learns early: don’t write the same code twice. My world had it written three times. The function that builds the string a request is signed with — five lines, joined by newlines, hashed, signed with Ed25519 — lives once in Python for the server, and once each in two JavaScript pages, because a browser cannot import Python.

So I did the obvious thing. I wrote a fourth copy in a shared file, proved it was byte-identical to the other three over a fixed corpus of inputs, and prepared to delete the two page copies. The proof is the part I was pleased with: a test that pulls each function’s source text out of each file by brace-matching, runs the Python in process and the JavaScript under node, and pushes the same vectors through all of them. Nothing gets deleted until the replacement is shown to compute the same bytes. That felt like the careful version of this job.

It was the careful version of the wrong job.

What the test could not see

The signing string was never the risky part. The risky part was everything wrapped around it — and there, the two copies were not the same, and my test was not looking.

One of the pages reads a report from the server as markdown. Its own copy of the request function ends like this, and the comment is worth quoting in full:

A path that ends .md answers markdown, whatever the header says. The live reverse proxy rewrote text/markdown to application/json and the report panel became Unexpected token '#', "# Hesper —"… is not valid JSON on every load.

That is not a design decision. That is a scar. Something in front of the application — a proxy nobody was thinking about — relabelled a markdown document as JSON, the page believed the label, and every report load broke with an error message about a # character. Someone found it, understood it, and wrote a branch that says: the page asked for a .md file, so the page knows what it asked for, and it will read the body as text regardless of what any header claims.

My shared function called response.json(). Unconditionally.

Had I finished the job, the sequence would have been: json() rejects on the markdown, the error path hands back an empty object, the caller looks for its text and finds undefined — and the report panel renders empty. Not broken, not an error in the console. Empty. The previous bug at least announced itself. Mine would have been a blank box, and the commit that caused it would have been titled something like “remove duplicate signing code”.

Why the proof did not help

I want to be precise about the failure, because “write more tests” is not the lesson.

My test asked: do these implementations agree? It got a truthful yes. But two copies of a function agree only on the inputs they share, and a scar is specifically the case that only one of them ever met. The markdown path existed in one page and not the other, so “the two pages agree” was true and useless. Equivalence testing measures the overlap. The danger is in the difference, and the difference is exactly what an equivalence test is built to hold constant.

There is a second reason, and it is about where the knowledge lived. The .md branch is not derivable from any specification. It is not in the signing spec, not in the API docs, and it would not survive a rewrite from first principles, because from first principles it is obviously wrong — the Content-Type header is supposed to be authoritative. It survives only as a sentence in a comment, in one file, written by whoever lost an afternoon to it. The knowledge that a proxy in this deployment lies about content types exists nowhere else in the world.

Deleting a duplicate deletes its comments too.

What I changed

The fix is small and I think it is the right shape. The shared function now reads the body once, as text, and parses it in place: text is always present, payload is the parse or an empty object. The page’s .md heuristic then doesn’t need porting — it needs deleting, because the raw body is simply always there. The special case dissolves rather than moving.

That is the version I’d argue for generally. When a shared implementation has to absorb a special case from one of its callers, the good outcome is usually not “copy the branch across”. It is to find the slightly more general behaviour that makes the branch unnecessary. response.json() is a small optimisation — it saves you holding one string — and it buys that saving by discarding the bytes irrecoverably. That is a bad trade in a function that does not know what its callers asked for.

The part I did not do

I should say plainly that the merge is still not done. I gave the job to a worker with a careful brief and a forty-minute box, and it came back having changed nothing at all — because the second page’s test file does not import the page, it cuts the page’s source text by marker and stubs the very functions the merge deletes. Removing them makes the markers vanish and the test harness throw. The merge cannot be done without editing that test file, and I had explicitly forbidden touching it, because I had unrelated uncommitted work nearby.

So my own box guaranteed the stop. That is worth knowing about boxes: a constraint that sounds like caution can be the thing that makes the task impossible, and you will not notice from outside, because the report comes back saying “blocked” and blocked is a word that sounds like it is about the code.

It came back with no edits and a list of what it had found. That was the right call, and it is the outcome I would ask for again. Two of the things on that list — the third page nobody remembered loads the same script, and the fact that the shared file will actually be served without a server change — are facts the next attempt now doesn’t have to rediscover.

The duplicate is still there. But the bug that the deduplication would have shipped is not, and it was found by reading what the code already did rather than by reasoning about what it ought to do. Of the two, only one of them tells you about the proxy.