DEV Community: stepinto.dev

Latent State Is the Fields You Never Logged

stepinto.dev — Mon, 02 Nov 2026 07:23:35 +0000

The last post ended with a challenge. Four weights fitted from logs can learn a room, but give that room a door that opens and closes on a schedule the logger never records, and the best a linear model can do is average over the door.

The log has three columns: the room temperature, the outside temperature and whether the heater is on. When the door opens the room cools faster, and every row written while it is open looks like a row from a room that is simply worse at holding heat. The model sees the effect and never the cause, so fitting the same three columns harder gets it nowhere. What the log does still have is order. A room that was cooling steadily and then drops three degrees in one step has told you something, even if no column says what.

The 102 post described how we might work around this: give the model a private field it keeps for itself, and let it decide what to put there. It also promised to explain how such a field can be learned when nobody ever sees it.

This post builds the room with the door, watches the four-weight model fail on it, gives the model one private field, and watches the field turn into the door. The maths comes at the end, because by then it describes something you have watched run. The playground has the door in it now, so everything below can be rerun in your browser.

An invisible door (according to the data)

I'm using the same simulated room from the last post, with one addition. Someone keeps opening the door, and while it is open the room leaks heat three and a half times faster.

const LEAK_CLOSED = 0.07;   // the 103 room
const LEAK_OPEN = 0.25;
let doorOpen = false;       // the room's secret; never written to the log

function someone() {
  // opens the door about once every 25 steps, leaves it open about 8
  if (doorOpen) { if (rand() < 1 / 8) doorOpen = false; }
  else if (rand() < 1 / 25) doorOpen = true;
}

function realRoom(state: State, action: Action): State {
  const heaterOn = heaterAfter(state, action);
  const leak = (state.outsideTemp - state.roomTemp) * (doorOpen ? LEAK_OPEN : LEAK_CLOSED);
  const heat = heaterOn ? REAL_HEAT : 0;
  return { roomTemp: state.roomTemp + leak + heat + gauss() * NOISE, outsideTemp: state.outsideTemp, heaterOn };
}

The rule from the last post still holds: nothing below this line looks at doorOpen. The logger calls someone() before every step and writes down the same three fields it always did, so a row from the new log is indistinguishable from a row from the old one. Eighty episodes of sixty steps gives 4,800 transitions, and the door is open for 22 percent of them. Nothing in the log says which.

If you run devices in the field, this is every column your telemetry does not have. The window someone left open, the second heater in the room that is not on your network, the pump that was switched to manual for an afternoon. The dynamics change and the log does not say why.

What four weights do with a door

First I refitted the four-weight model on the new log, with the same features, the same twenty-line training loop and ten thousand epochs.

weight	sealed room (103)	with the door	truth, door closed
room	-0.074	-0.037	-0.07
outside	0.069	0.040	0.07
heater	1.19	0.97	1.2
bias	0.077	-0.41	0

I expected the loss to get worse, and it flattens at 0.29 against 0.01 in the sealed room. I didn't expect the shape of the damage. The model has not averaged over the door, which would have given a room weight somewhere between the closed and open leak rates. It has halved the room weight and gone looking for the lost heat in the bias.

The reason is that the door is not independent of the things the model can see. An open door drags the room down, so in the log a cold room and a big drop arrive together, and the only lever the model has for "cold room" is the room weight. It pushes that weight towards zero to account for the drops, then pulls the bias negative to make the sums balance. A hidden variable that moves with the visible ones bends the fit, which is rather worse than adding noise to it.

You can see the bend when the model is asked to forecast. Later in the post there is a room at minus four with the heater on, where the door opens at step 10. Ask this model at step 13, with the room at 7.8 degrees and falling fast, what the next five steps look like, and it says the room warms to 8.3. The real room goes to 2.7.

One private field

The 102 post sketched the shape of the fix as a class with a field nobody outside can read:

class WorldModel {
  #state: Float32Array;  // s_t lives here, and nowhere in your logs
  observe(o: Observation) { /* fold the new reading into #state */ }
  act(a: Action): Distribution<Observation> { /* predict, given #state and a */ }
}

Here is the smallest version of that I could make work. The private field is one number. act is the four-weight model from 103, plus a second weighted sum that the field switches on. observe folds what just happened into the field, using a weighted sum of its own, squashed through tanh so the field stays between minus one and one.

type Weights = {
  // act: change in room temperature = base + field * extra
  room: number; outside: number; heater: number; bias: number;
  fieldRoom: number; fieldOutside: number; fieldBias: number;
  // observe: next field = tanh(a weighted sum of the field and what just happened)
  uField: number; uRoom: number; uOutside: number; uHeater: number; uChange: number; uBias: number;
};

class WorldModel {
  #field = 0;              // s_t lives here, and nowhere in the logs
  w: Weights;
  constructor(w: Weights) { this.w = w; }

  reset() { this.#field = 0; }

  act(state: State, action: Action): State {
    const f = inputs(state, action), w = this.w;
    const base = w.room * f.room + w.outside * f.outside + w.heater * f.heater + w.bias;
    const extra = w.fieldRoom * f.room + w.fieldOutside * f.outside + w.fieldBias;
    return { roomTemp: state.roomTemp + base + this.#field * extra, outsideTemp: state.outsideTemp, heaterOn: f.heaterOn };
  }

  observe(state: State, action: Action, nextState: State) {
    const f = inputs(state, action), w = this.w;
    const change = (nextState.roomTemp - state.roomTemp) / 5;
    this.#field = Math.tanh(
      w.uField * this.#field + w.uRoom * f.room + w.uOutside * f.outside +
      w.uHeater * f.heater + w.uChange * change + w.uBias);
  }
}

Thirteen numbers, against four. Seven of them say what the field does to the prediction; six say what the model should write into the field after each step. Nothing in there mentions a door. The field is allowed to be anything between minus one and one, and the model gets to decide what it means.

Two small things changed alongside. inputs is features with the temperatures centred and scaled (room temperature minus 17, outside minus 7, both divided by five), and the change the model observes is divided by five too. In the last post I left the inputs raw and paid for it with ten thousand epochs down a long thin valley. This time the loop below is more expensive per epoch, so I took the shortcut the 103 post mentioned, and it converges in three thousand.

The other change is to the observe signature. The 102 sketch took an observation; this one takes the whole transition, because the thing the field most needs to know is how the room moved compared with what the model expected, and that needs both ends of the step.

Training through the field

The 102 post promised to explain how this gets trained. The field is never in the log, so there is no column to compare it against. The thirteen weights have to be judged by the only thing that is in the log, the next temperature, and six of those weights only affect the next temperature indirectly, by changing what gets written into the field, which changes the prediction a step later, and the step after that.

So the gradient has to flow through the field. In 103 each row of the log was its own small problem, and the loop could visit rows in any order. Now a row's prediction depends on the field, the field depends on the previous row, and so on back to the start of the episode. The training loop walks each episode forwards, remembering what the field was at every step, and then walks it backwards, asking at each step how much that step's field mattered to everything that came after it.

function train(log: Transition[][], epochs: number, lr: number) {
  const w = {} as Weights;
  for (const k of keys) w[k] = k.startsWith("u") ? (rand() - 0.5) * 0.2 : 0;
  const losses: number[] = [];
  const n = log.flat().length;
  for (let epoch = 0; epoch < epochs; epoch++) {
    const g = {} as Weights;
    for (const k of keys) g[k] = 0;
    let loss = 0;
    for (const episode of log) {
      // forwards through the episode, remembering what the field was at every step
      const steps = [];
      let field = 0;
      for (const t of episode) {
        const f = inputs(t.state, t.action);
        const target = t.nextState.roomTemp - t.state.roomTemp;
        const base = w.room * f.room + w.outside * f.outside + w.heater * f.heater + w.bias;
        const extra = w.fieldRoom * f.room + w.fieldOutside * f.outside + w.fieldBias;
        const err = base + field * extra - target;
        loss += err * err;
        const change = target / 5;
        const next = Math.tanh(w.uField * field + w.uRoom * f.room + w.uOutside * f.outside + w.uHeater * f.heater + w.uChange * change + w.uBias);
        steps.push({ f, change, field, extra, err, next });
        field = next;
      }
      // backwards through the episode: how much did each step's field matter to everything after it?
      let dField = 0;   // d loss / d (field after this step)
      for (let i = steps.length - 1; i >= 0; i--) {
        const s = steps[i];
        const dPre = dField * (1 - s.next * s.next);           // through the tanh
        g.uField += dPre * s.field; g.uRoom += dPre * s.f.room; g.uOutside += dPre * s.f.outside;
        g.uHeater += dPre * s.f.heater; g.uChange += dPre * s.change; g.uBias += dPre;
        g.room += s.err * s.f.room; g.outside += s.err * s.f.outside; g.heater += s.err * s.f.heater; g.bias += s.err;
        g.fieldRoom += s.err * s.field * s.f.room; g.fieldOutside += s.err * s.field * s.f.outside; g.fieldBias += s.err * s.field;
        dField = s.err * s.extra + dPre * w.uField;            // on to the step before
      }
    }
    for (const k of keys) w[k] -= lr * g[k] / n;
    losses.push(loss / n);
  }
  return { w, losses };
}

const { w, losses } = train(log, 3000, 0.3);

The forwards half is act and observe inlined. The backwards half is the chain rule, and two lines of it carry the whole idea. dPre is how much the loss would change if the field written at this step were nudged, pulled back through the tanh. The last line passes that on to the step before, because the step before chose the field this step started with. Everything else is the err * input pattern from 103, applied to whichever weight the line is about.

This is backpropagation through time, and it is the reason recurrent models are trained on episodes rather than on rows. Three thousand epochs over 4,800 rows takes about half a second in Node 23. The six u weights start at small random values rather than zero, because with every u at zero the field never moves, nothing depends on it, and the gradient for those weights is exactly zero forever. The seven prediction weights start at zero as before.

Mean squared error per epoch for the latent model, with three reference lines. The four-weight model stopped at 0.29. A model that could see the door would reach 0.01, the level of the draughts. The same model told the door one step late gets 0.17, and the latent model settles just under it.

Download the data (CSV)

The two dashed lines show what the model is being asked to do. I fitted a seven-weight model that is told the door state, which is cheating, to find out what the best possible fit looks like. Scored normally it reaches the noise floor. Then I gave the same model the door state one step late, so it only learns the door has moved after seeing the step on which it moved, and it gets 0.174. The step the door moves on is a surprise by definition, and the 310 steps where it moved account for 0.165 of that on their own. The latent model gets 0.172.

That second line is a reference rather than a floor, and the latent model sitting under it is the clue. The late-door model insists the door is wherever it was a step ago. A model that knows the door a step late and also knows how often it moves (about one step in eight while it is open, one in twenty-five while it is shut) can hedge, adding a little leak to every closed step in case the door has just opened, and that scores 0.163. Refitting the seven weights on the late door state lands in the same place. So the latent model is about a hundredth above what noticing the door can reach with this shape of model. None of these numbers is a true lower bound, either: all of them are scored on the 4,800 rows the models were fitted to, and a model with a better shape could go lower.

Here is what it learned, with the temperature weights divided by five so they read per degree.

weight	learned	weight	learned
room	-0.111	uField	0.007
outside	0.078	uRoom	-0.049
heater	1.21	uOutside	0.031
bias	-0.92	uHeater	0.50
fieldRoom	0.010	uChange	-2.19
fieldOutside	0.015	uBias	-0.39
fieldBias	-1.83

Read the right-hand column as the recipe for the field. The weight on uChange is by far the largest: the field is mostly a function of how much the room moved last step, with the heater and the temperatures subtracted off so that a drop the base model already expected does not count. The weight on uField, the field's memory of itself, is almost nothing. For this room the model decided it did not need memory, because one step of an open door is loud enough to hear on its own. That changes when the door gets quieter, further down.

The left-hand column is less tidy than in 103. The room and outside weights are no longer equal and opposite, and the field's effect is almost all in fieldBias. The model is not obliged to factor the room into "closed door physics plus a door term" the way I would, and the gradient found a different split that fits the log just as well. A private field has no label on it. It holds whatever the model found useful, and you judge it by the predictions, as the 102 post said you would have to.

The field finds the door

The test is the same unseen room as in the last post: 22 degrees inside, minus four outside, colder than anything in the log. The heater is on throughout. The door opens at step 10 and closes at step 20, and the models are not told.

Two things are different about how the models are run. First, each one sees the real reading at every step and predicts the next one, the way a thermostat would, rather than running thirty steps blind from the start. With a door it cannot see, no model could run thirty steps blind, and the point of the field is that the model notices. Second, at three chosen steps, each model is asked to run five steps blind from where it is, which is the "what if" that world models are for.

Top: the real room, with five-step forecasts from both models branching off at steps 5, 13 and 23. Bottom: the private field after each step, with the door state it never saw dashed over it. The field is near zero for ten steps, 0.91 the step after the door opens, and 0.12 the step after it closes.

Download the data (CSV)

The strip at the bottom is the result I was after. The field sits a little below zero while the door is closed, jumps to 0.9 on the first step after it opens, stays high while it is open, and drops back the step after it closes. The model was never told there was a door, and the field is a door anyway, because a door was the thing in the room that the log could not explain and a single number could.

Step by step at the two moments that matter:

step	door	real room	four-weight, one step ahead	latent, one step ahead	field after
10	closed	17.19	17.16	16.97	-0.15
11	open	13.14	16.96	16.90	0.91
12	open	10.10	13.06	11.16	0.86
13	open	7.76	10.13	8.52	0.81
20	open	1.94	2.69	2.27	0.59
21	closed	2.83	2.27	1.77	0.12
22	closed	3.55	3.13	3.56	0.15

Step 11 is wrong for both models and has to be. Nobody could have predicted the door. From step 12 the latent model is within a degree and closing, while the four-weight model is three degrees adrift and stays there. Step 21 is the same story in reverse. Over the thirty steps the one-step error is 1.16 degrees for the four-weight model and 0.78 for the latent one; leave out the two steps the door moved on and it is 0.95 against 0.32.

At step 13 the latent model has had two steps to notice the door, and its field reads 0.81. Asked for five steps blind, it says the room will fall from 7.8 to 2.7, and the room falls to 2.7. The four-weight model, from the same reading, says 8.3. It has no way to represent "the room is currently leaking faster than usual", so it cannot condition on it, and its bent physics sends the forecast the wrong way.

forecast from	real, five steps on	four-weight	latent
step 5, door closed	17.2	17.7	17.1
step 13, door open	2.7	8.3	2.7
step 23, door just closed	6.8	5.3	6.1

The strip also shows the field drifting down from 0.91 to about 0.55 over the ten open steps. It is reading the size of the drop, and the drop shrinks as the room gets closer to the temperature an open room would settle at. The model has no memory to hold the field up because, as the weights table said, it did not learn any. Make the door quieter and that changes. Rerunning the whole script with the open-door leak at 0.15 instead of 0.25 brings the memory weight from 0.007 to 0.08, and at 0.12 it is 0.26: when one step is no longer enough to tell, the model learns to add up several. At 0.10, where the door only adds a few hundredths to the leak, the field stops tracking the door at all, and the latent model's loss sits above the one-step-late line. There is a signal it cannot find in 4,800 rows, and the answer, as with most problems in this series, is more log.

Now the notation

Everything above fits in two lines. The private field is (h), the readings the logger can see are (o), and the action is (a).

$$h_t = f(h_{t-1},\ o_{t-1},\ a_{t-1},\ o_t)$$

$$\hat{o}_{t+1} = g(h_t,\ o_t,\ a_t)$$

The first line is observe: the new field is a function of the old field and the step that just happened. The second is act: the predicted next reading is a function of the field, the current reading and the action. In this post (f) is a tanh of a weighted sum and (g) is two weighted sums, and training them was gradient descent with the chain rule run backwards through the first line.

Put the field and the readings together and call the pair (s_t), and the second line is the world model equation from the 102 post, (P(s_{t+1} \mid s_t, a_t)), with the probability dropped because the model predicts a single number. The state the equation conditions on was always meant to include the fields you never logged. That is why it is called latent: the field is hidden from the logger, but the maths had a place for it all along.

How DreamerV3 does the same job

The part of this post that carries over most directly to the research systems is the one it spent longest on. Nobody tells DreamerV3 what to keep in its recurrent state either. The state has to hold whatever a single observation cannot show, such as how fast something is moving or where an object went when it left the frame, and it learns to hold those things for the same reason the field learned the door: the predictions were wrong without them, and the gradient, walking back through each sequence, found which numbers would fix that.

The architecture carries over less neatly. DreamerV3 calls its world model a recurrent state-space model, and it has more parts than my two methods:

a sequence model, a GRU, that carries a recurrent state (h_t) forward from (h_{t-1}), the last action and the last latent (z_{t-1})
an encoder that reads the new observation alongside (h_t) and produces (z_t), a stochastic latent made of 32 categorical variables with 32 classes each
a dynamics predictor that guesses (z_t) from (h_t) alone, before the observation arrives
a decoder, with heads for reward and for whether the episode carries on, that reads (h_t) and (z_t) together

My observe does the work of the sequence model and the encoder in one line, and my act is closest to the decoder. Three of the differences matter, and each of them shows up somewhere in this post.

The first is where the readings go. My act is handed the current reading, so the field only has to carry what the reading leaves out, and one number covers the door. DreamerV3's decoder has nothing but the state to work from, so the state has to carry everything, the equivalent of the temperature included. That is why it is hundreds or thousands of numbers wide, and it is what lets the model imagine many steps ahead with no observations at all. My five-step forecasts get away with feeding the predicted temperature back in as the next reading, which works only because the temperature is the whole of what the logger sees.

The second is the guess made before the reading. DreamerV3 keeps two versions of (z_t) at every step: the dynamics predictor's guess from (h_t), and the encoder's answer once the observation is in. Part of its training loss is the gap between the two. Step 11 in the table above is that gap in miniature, where the model expected a shut door and the reading said otherwise. My model only ever has the answer, so when it forecasts blind its field stays wherever it was. It cannot imagine the door shutting at step 20, or opening in the first place. DreamerV3's guess is a distribution, so an imagined rollout can open the door in some samples and leave it shut in others.

The third is how the training is fed. The backward walk through each sequence is the same, but DreamerV3 cuts its experience into chunks of 64 steps drawn from a replay buffer that keeps filling while it acts, and its loss has more than one term: how well it reconstructs the observation, the reward and the continuation, plus two terms that pull the guess and the answer towards each other, weighted 0.5 and 0.1. Mine is one squared error over eighty fixed episodes.

The 101 post joked about representation collapse, where a model scores perfectly by declaring every state identical. That failure needs the model's target to be something the model produces itself. JEPA-style models, from LeCun's line of work, predict the representation of the next observation rather than the observation, so a representation that never changes predicts itself perfectly, and they keep a separate, slowly updated target encoder behind a stop-gradient to prevent it. My model's target is a thermometer reading, which it has no way to change. A constant field earns it nothing, and the model falls back to the four-weight fit and its 0.29. DreamerV3 has the same protection, because it reconstructs its observations, and a quieter risk from the other side: the term that pulls the encoder's answer towards the guess would, pushed far enough, teach the encoder to ignore the observation. DreamerV3 stops penalising that gap once it is below one nat, which it calls free bits.

The nearest thing this post has to collapse is a field that goes unused, and that is less final than it sounds. With every u weight at exactly zero the gradient is exactly zero, which is why they start small and random, but near zero it is small and still there. When the open-door leak came down to 0.10, the field stopped tracking the door because the signal was too faint to find in 4,800 rows, which is a shortage of log and not a trap the training fell into.

Try it

The playground has a scenario switch at the top. In the door scenario, recording adds the door, training runs the four-weight model and then the latent one, and the right-hand pane runs the room at minus four with a slider for where the five-step forecast starts. Drag that slider across step 10 and watch the orange forecast turn the wrong way. The open-door leak has a slider too; bring it down towards the closed rate and watch the memory weight in the latent model's table climb, then watch the field stop finding the door altogether.

The playground runs the same code with Math.random where the script's seed is, so your numbers will differ from the ones above by a little and agree with them in shape. The data behind each chart is linked under it.

The next post puts this model next to an LLM. One predicts the next token of text, the other predicts the next state of a room, and the interesting part is where an agent would want both.

A Piece That Breaks Another Piece

stepinto.dev — Thu, 29 Oct 2026 19:30:12 +0000

It was all broken by me really, or built like a clumsy caveman

Trying to have something right afterwards

I've been building a series of pages where the computer generates the pattern: tin-glazed tiles painted by rule, then cut tile and poured cement, then heraldry and knotwork. They've been travelling round Europe, borrowing from the art and the history of each place, and trying to capture something about how patterns repeat across the whole of the artistic world: the same rule turning up in a different material somewhere else. This one is Barcelona. I've stood in front of Casa Batlló, and walked a good deal of that city in Gaudí's footprints, and the thing you notice about his surfaces once you're close is that none of them are made of anything whole. The bench at Park Güell, the dragon on the stair below it, the chimneys on the Pedrera roof and the pinnacles of the Sagrada Família are all trencadís: tiles that somebody broke with a hammer and set back, shard by shard, in lime.

So Trencadís is a page that starts with a wall it didn't paint. It takes Azulejería's tiles, grown from a seed by the same engine, and breaks them.

The banc preset. Park Güell's bench: white, cobalt and yellow, a third of the tiles painted, the surface undulating.

A piece that breaks another piece

Every page in this series so far has made its own picture. This one consumes somebody else's. The source wall is Azulejería's flora, the rosette quartered on one corner, the bud on the opposite one, half a flower on each edge, painted by the engine's makeTile with the same drifting brush and the same wash laid thin twice. The page asks the engine for four paintings of the design at the pixel size they'll be seen at, and keeps them as the tiles the wall was laid from.

I copied the flora motif and its four painters into the page rather than importing them. Sixty lines. It felt wrong for about a minute, and then it didn't: the engine holds the brush, each page holds what it paints with it. Azulejería's motifs belong to Azulejería. If Trencadís wants a rosette it draws one with the engine, the same way Jerez draws a vine, and the fact that it draws the same rosette is the point of the piece rather than a reason to share code.

The crack

A broken tile is a Voronoi diagram. Not exactly, but close enough that nobody at the bench will argue. Scatter points, give each point the region of the plane nearer to it than to any other, and you get convex cells with straight edges meeting at threes, which is what a sheet of glaze does when it goes under a hammer.

The points sit on a grid of cells about a third of a tile across, each one jittered nearly half a cell in either direction, and one in twelve is missing, so its neighbours grow into the gap and some shards come out bigger than others. The Voronoi itself is twenty lines: for each site, start with a square and clip it by the bisector with every neighbour, nearest first, stopping once the next neighbour is more than twice as far as the cell's farthest corner, because it can't touch the cell after that.

Then every cell goes through the cutter. It's shifted and turned by the fraction a hand allows, its corners land a touch off the drawing, its long edges bow, and it's inset from the joint by a mitred offset so the mortar between two shards is the same width along an edge as at a point. That cutter was Alicatado's, and more on that below.

The same cutter on two kinds of piece. Alicatado's alcázar preset on the left, Trencadís's pinacles on the right. Cut on one side, broken on the other, mitred and bedded the same way.

In the bucket, or where it fell

A shard is a piece of a tile, so the page has to decide which tile and which piece. There are two honest answers. Either the shard is still where it broke, in which case the piece of the wall underneath it is simply the piece of the wall underneath it, and the rosettes read through the cracks. Or it went in the bucket with everything else, and came out somewhere else, turned some other way.

The intact slider is the share of shards that stayed put. At one, the wall is only cracked. At zero, every shard is a random piece of a random tile at a random angle, which is what a mason does with a bucket of pieces and no particular plan. In between you get a wall where the pattern keeps half-surfacing, a scalloped ring that runs across three shards and then stops, which is what the bench actually looks like when you get your face close to it.

I've had a year of breaking things and of things being broken, so a slider for how much of the original survives was always going to get built. It turns out the honest setting is somewhere around a third.

The same seed and the same crack at intact 0, 0.5 and 1. Left, everything in the bucket. Right, the wall as it broke.

The sencer preset, up close. Azulejería's wall, broken in place. The joints are the only thing this page added.

Sampling a shard in place is a clip and a drawImage of the tile under it, mirrored the way the module repeat lays it. A displaced shard is the same clip with the tile drawn around a random point at a random turn. The one surprise was the rim of the tile: the engine thickens the glaze at the edge of every tile with a faint square stroke, and on a wall that is only cracked those squares showed through as a grid. Real shards don't carry their edges, they went in the bucket with everything else, so the page crops three per cent off every side of the tile before it samples.

The bench

Trencadís is a curved-surface technique. You can't bend a tile, so you break it and lay the pieces on the curve, and that's the whole reason it exists. A flat trencadís wall is a mosaic with a bad excuse.

The page's surface is a height field: a long sine wave along the wall, bent by a slower one across it, with an amplitude the curve slider sets. The normal of the surface at each shard's centre is taken against the light (the same light angle Alicatado uses, with a height to it now), and the difference from flat lights the shard or shades it. The mortar follows the same surface, sampled coarsely into a small canvas and drawn smoothly over the lime before the shards go on, so the joints dip into the troughs with the pieces. The troughs also sit a little in their own shadow, which is cheap and does more than the lighting.

The pedrera preset at curve 0 and curve 1. The chimneys on the roof of La Pedrera are broken marble with a few broken bottles, and they are nothing but curve.

My first shading was far too strong and the Pedrera chimneys looked like they'd been left out in the rain. The shadow is cooler and lighter now, a lime-coloured surface throwing back a bluish shade rather than going black, and the tin-white shards on the bench stay white on the lit side, which is what the bench does at midday.

The cutter moves house

Trencadís was the second page to want Alicatado's cutter, which is the point at which something stops being one page's and becomes the engine's. offsetPoly (the mitred inset), cutPiece (the shift, the turn, the nicked corners, the bowed edges), the edge relief that lights one side of a standing piece and shades the other, the grain for the mortar, and the small polygon maths every page kept rewriting all moved out of Alicatado into the package as azulejeria/pieces, with the Voronoi beside them for pieces that are broken rather than cut.

Moving a function that draws random numbers is the dangerous kind of refactor on these pages, because every wall is deterministic per seed and an extra rng() call anywhere shifts everything after it. So before touching anything I rendered all nine of Alicatado's presets, main canvas and the card thumbnails, and hashed the bytes. Then moved the cutter, rendered them again, and compared. Identical, which is the only acceptable answer. The same check ran on every engine page for the two small engine changes Delft needed, below, and came back identical each time.

The next customer for the cutter is Sutton Hoo, garnets in gold cells, which was blocked on this move and now isn't.

Delft

Delft is the engine sent north, to see whether it works for someone else's country with no help. A Delft tile is a picture: a ship, a bird on a branch, a windmill, a tulip, a pikeman or a child bowling a hoop in the middle of a tin-white square, with a corner motif in each corner (the ossenkop, the spider's head, the fleur-de-lis) that completes where four tiles meet. Cobalt on white, or manganese when the painter had it.

The schouw preset: everything mixed, in roundels, the way a stove surround came. Every tile is one of eight paintings, and each painting picked its own figure.

It nearly worked with no help. The engine's wall mirrors or turns every other tile so that quarter designs complete across the joints, and a picture of a ship can't be turned upside down. The fallthrough branch of the wall already laid tiles the same way up for any repeat it didn't recognise, so a whole repeat was a word in a list. The second thing was that a wall draws from four paintings of its design, which is plenty when the design is a rosette, and makes a wall of ships four ships. A variants option on createWall lets Delft ask for eight. The figure is chosen in the painter from the painting's own random stream, not when the design is grown, so each of the eight is a different ship. That was the whole engine change, and both pages' bytes were checked before and after.

Then the figures. I drew them from parts, the way I'd drawn Leonor's first lions and Knotwork's first hound: a trapezoid for the mill, a drop for the bird, a hat and a coat for the pikeman. They looked, for the third time in this series, like toys. This is now a rule rather than a lesson: a figure that is a convention copied by hand for three hundred years gets traced from a drawing, not built from rules.

So I asked an image model for six, on the terms the tracer wants: one solid gold fill, a thick even black line around every part, red for the parts to wash lighter, nothing else in the frame. It gave me a fluyt with red sails, a robin with a red breast, a post mill with a red cap, a tulip, a pikeman with a red feather in his hat, and a boy with a red hoop. The forty-line tracer from the heraldry post turned each one into loops. Gold became the cobalt wash, laid twice so it pools; red became a lighter wash over the glaze; black became the ink, laid last. The mill's lattice sails keep their holes because the silhouette is filled even-odd.

The six drawings, and the six tiles traced from them. The soldier is in manganese, the tulip in the early polychrome.

One thing the traced figures couldn't do at first was listen to the sliders. The brush slider is the engine's line weight, and a traced line is a filled shape at the drawing's own width. So the brush object the engine hands every painter now carries hand and brush as the state has them, and the traced ink drifts with the hand like the wash does, and is stroked wider when the brush is loaded past the drawing's line. A lighter brush can't thin a traced line without painting a halo over the wash outside it, so below one it stays the drawing's weight, and the page says so. Jerez's horse and Rosa y Granada's pomegranate got the same.

In the package

azulejeria is at 2.3.1. The cutter is its own module, next to the knots, and uses nothing from the wall except the seeded random.

npm install azulejeria

import { voronoi, cutPiece, relief } from 'azulejeria/pieces';

cutPiece takes a polygon and how far it may stray and gives you back the piece as laid and its glazed face inside the joint. voronoi gives you the cells of a scatter of points. relief lights the edges. The README has the rest, and the whole repeat and variants are in the wall's options for anyone whose tiles are pictures.

Sebka is next, the brick lattice of the Giralda, a piece that is entirely light. Then Sutton Hoo.

A Claude Client in One Go File

stepinto.dev — Thu, 29 Oct 2026 07:24:31 +0000

Last week I wrote a Claude client in bash, parsed the stream with regular expressions, and pinned it as the thing to beat. This week it's Go, which has it rather easy by comparison.

Go is the first language in the series where the standard library covers everything the spec asks for: an HTTP client with TLS, a JSON codec, a buffered line reader, and a timezone database baked into the binary. The whole client is 175 lines in one file, and it runs from a scratch image.

The code is at github.com/AndyCross/claude-hot-path and the leaderboard is at /claude-hot-path/. The spec, which every client has to pass, is on that page.

Reading the stream

An SSE stream is lines. event: lines, data: lines, blank separators, and the occasional ping. The client only acts on data: lines, so a bufio.Scanner over the response body with a prefix check is the entire transport layer:

sc := bufio.NewScanner(resp.Body)
sc.Buffer(make([]byte, 64*1024), 1<<20)
for sc.Scan() {
    data, ok := strings.CutPrefix(sc.Text(), "data: ")
    if !ok {
        continue // event:, ping bodies, blank separators
    }
    var ev event
    if err := json.Unmarshal([]byte(data), &ev); err != nil {
        return nil, "", err
    }
    switch ev.Type {
    case "content_block_start":
        content = append(content, *ev.ContentBlock)
        partial = append(partial, strings.Builder{})
    case "content_block_delta":
        switch ev.Delta.Type {
        case "text_delta":
            os.Stdout.WriteString(ev.Delta.Text)
            content[ev.Index].Text += ev.Delta.Text
        case "input_json_delta":
            partial[ev.Index].WriteString(ev.Delta.PartialJSON)
        }
    case "content_block_stop":
        if content[ev.Index].Type == "tool_use" {
            if s := partial[ev.Index].String(); s != "" {
                content[ev.Index].Input = json.RawMessage(s)
            }
        }
    case "message_delta":
        stop = ev.Delta.StopReason
    }
}

The sc.Buffer call matters. The default scanner token limit is 64 KB and a single data: line can be longer than that if a tool argument is large, so the limit goes up to a megabyte. Bash had no such limit and no such safety either.

One struct does for every event. The payloads share a shape, type and index at the top and a delta or a content_block underneath, so a single event type with all the fields and the unused ones left zero is simpler than a type per event:

type event struct {
    Type         string `json:"type"`
    Index        int    `json:"index"`
    ContentBlock *block `json:"content_block"`
    Delta        struct {
        Type        string `json:"type"`
        Text        string `json:"text"`
        PartialJSON string `json:"partial_json"`
        StopReason  string `json:"stop_reason"`
    } `json:"delta"`
}

Echoing the assistant turn

Tool use is a conversation. After the first stream ends with stop_reason: "tool_use", the second request has to carry the user message, the assistant's whole turn including the tool_use block with its assembled input, and then a user message holding the tool_result. The block type that content_block_start decodes into is also the type that gets marshalled back out, which is where omitzero earns its place:

type block struct {
    Type      string          `json:"type"`
    Text      string          `json:"text,omitzero"`
    ID        string          `json:"id,omitzero"`
    Name      string          `json:"name,omitzero"`
    Input     json.RawMessage `json:"input,omitzero"`
    ToolUseID string          `json:"tool_use_id,omitzero"`
    Content   string          `json:"content,omitzero"`
}

A text block marshals as type and text, a tool use as type, id, name and input, and a tool result as type, tool_use_id and content, all from the one struct. Input is a json.RawMessage because the fragments arrive as text and there is no reason to decode them into a map only to encode them again. The tool itself reads the timezone out of it with a one-field anonymous struct.

The loop in main is then the agentic loop in its smallest form: send, print, and if the stop reason was tool_use, run every tool block, append two messages, go round again.

The one thing the standard library does not have

Timezones. time.LoadLocation("Europe/London") reads the system's zoneinfo, and a scratch image has no system. Go ships its own copy of the database at $GOROOT/lib/time/zoneinfo.zip and LoadLocation falls back to it, so the Dockerfile copies that one file into the final image, next to the CA bundle:

FROM golang:1 AS build
WORKDIR /src
COPY client.go ./
RUN go mod init client && CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /client client.go

FROM scratch
COPY --from=build /client /app/client
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/ca-certificates.crt
COPY --from=build /usr/local/go/lib/time/zoneinfo.zip /usr/local/go/lib/time/zoneinfo.zip
ENTRYPOINT ["/app/client"]

The alternative is import _ "time/tzdata", which embeds the database in the binary and adds about 450 KB to it. For a leaderboard that ranks on size, the zip file in the image is the honest choice because the harness measures the artefact, and either way the dependency is paid for somewhere.

What it measures as

	Go	bash and curl
Artefact	5.8 MB	3.7 KB
Runtime	0	23.7 MB
Ship	5.8 MB	23.7 MB
Cold start, median of 100	1.7 ms	7.0 ms
Turnaround, median of 100	1.2 ms	19.1 ms
Client total, median of 100	4.8 ms	35.3 ms
Peak RSS	6 MB	11 MB
Lines of code	156	75

go1.27.2, linux/arm64, Apple M4 Max under Docker. The binary is built with -s -w and -trimpath, and nothing else.

The 5.8 MB binary is the number people will argue about. Most of it is net/http and its dependency on crypto/tls, and the rest is encoding/json, which since 1.27 is the v2 implementation underneath. You cannot get a Go HTTPS client much below five megabytes without leaving the standard library, and the series rules say a language with HTTP in its standard library uses it. Next week's .NET client, published with Native AOT, comes in at 5.4 MB for the binary and then pays 2.4 MB for the C library it links, which is the comparison I most wanted to see when I started this.

The cold start is where Go earns its place. Under two milliseconds from spawn to the first request on the wire, with no runtime to initialise and no shared libraries to load. The turnaround, which is the time between the first reply finishing and the second request arriving, is just over a millisecond: parse the tail of the stream, look up a timezone, build the second body, send it down the connection net/http kept open. I assumed most of that millisecond was time.LoadLocation opening the zoneinfo zip, and measured it: a variant that reads the TZif file straight from /usr/share/zoneinfo came out the same. What is left is the runtime. Every read on the socket is a wake-up through the network poller and a goroutine switch, where Rust and Zig make a blocking syscall and carry on, and at this scale that is the whole difference. Under five milliseconds of client time across the whole exchange, with nothing tuned and nothing worth tuning, is the number the others have to beat, and two of them do. The six megabytes of peak memory is the Go runtime's heap arena rather than anything the client allocated, and it varies by a couple of megabytes between runs.

How to run it

git clone https://github.com/AndyCross/claude-hot-path
cd claude-hot-path
./bench/bench.sh go

Docker and Python 3, no key. The Rust client is next, which is the first language in the series without HTTP in its standard library, and so the first one that has to pick a dependency and pay for it on the leaderboard.

Where AI Research Actually Happens, in Six Charts

stepinto.dev — Wed, 28 Oct 2026 07:24:20 +0000

Compute Isn't the Constraint argued that the UK's sovereign AI fund is buying the wrong input. That post was prose. This one is the numbers behind it, drawn so you can check them, with the source data under every chart as CSV. The sources are at the end.

Who publishes

Share of global AI publications by fractional count, OpenAlex via OECD.AI. China's dip between 2010 and 2015 is in the source data.

Download the data (CSV)

The United States and the EU together produced over half of the world's AI papers in 2000. They produce under a quarter now. Volume moved east and it is not coming back.

Who gets cited

Papers in the year's 100 most-cited AI papers, by country of the authors' institutions, Zeta Alpha. The UK figure is only available for 2022.

Download the data (CSV)

Volume and influence are different things. The US has never had fewer than 46 of the hundred most-cited papers in a year, and in 2022 had 68. The UK's 16 in 2022 is a respectable third place, and 11 of those 16 came from one laboratory, Google DeepMind.

Where the people are trained, and where they work

Elite AI researchers, defined as authors at NeurIPS, ICML and ICLR, by country of undergraduate degree and country of current employer. MacroPolo Global AI Talent Tracker 3.0.

Download the data (CSV)

The American lead is imported. US universities produce a quarter of the world's top AI researchers and US institutions employ six in ten of them. China produces the largest share of anyone and keeps about a tenth.

Which way they move

Net flow of elite AI researchers, employer country minus undergraduate country. Same source as above.

Download the data (CSV)

The UK is on the right side of this chart by 92 people. It is the smallest positive number that still counts as a win, and the 65% retention rate behind it is the figure a fund should be trying to move.

What the money looks like

Private AI investment in 2025, Stanford AI Index 2026. The Europe figure covers generative AI only and is the comparable number the Index reports.

Download the data (CSV)

This is the gravity. A lab funded from a £500m pot competes for people against an industry that raised two hundred and eighty-six billion dollars last year. The researchers it trains are worth more to the companies on the left of the chart than to the state that paid for them.

How far behind the published frontier sits

Lag between the best open-weight models and the closed frontier, by how you measure it. Epoch AI for the index and compute rows; Håvard Tveit Ihle's analysis of Epoch's benchmark data for the public and private benchmark rows, 2024 to 2026.

Download the data (CSV)

Pick the measure that flatters you and open weights are four months behind. Pick the one you cannot game and it is closer to ten. Measure by the compute actually deployed and it is sixteen. A team that trains on the public literature is a generation behind by construction, which is the whole argument of the earlier post in one bar.

Update, November 2026: the public and private benchmark rows are from Håvard Tveit Ihle's analysis of Epoch's benchmark data, not from Epoch itself; the caption and sources now say so. How Far Behind Are Open Weights, Measured draws the lag over time rather than as one bar.

The data

Every chart above has a CSV link. The charts and the CSV files come out of the same script, so the numbers in the pictures and the numbers in the files cannot drift apart.

Sources

Trajectories and Comparative Analysis of Global Countries Dominating AI Publications, arXiv 2509.25298, using OpenAlex data from OECD.AI with fractional counting.
The 100 most cited AI papers in 2022, Zeta Alpha's annual lists, which also give the 2021 and 2024 counts.
The Global AI Talent Tracker 3.0, MacroPolo, Paulson Institute.
The 2026 AI Index Report, Stanford HAI.
Open models lag state-of-the-art closed models by 4 months and Open vs. closed AI: how behind are open models?, Epoch AI.
How far behind are open models?, Håvard Tveit Ihle, May 2026, for the public and private benchmark lags.
UK's over-dependence on Google's DeepMind harms its global AI competitiveness, Verdict, for the DeepMind share of UK top-cited papers.

Knotwork by Rule

stepinto.dev — Sun, 25 Oct 2026 16:40:52 +0000

All the plans turn into old tickets, half unredeemed.

Old Tickets

The series has been working its way north. Andalusian tile, then English heraldry, then a medieval English floor, and now the furthest north it's going to get: the carpet pages of the Lindisfarne Gospels, the Book of Durrow and the Book of Kells. Whole pages of vellum given over to ribbons that go over, under, over, under, round every corner and back, in red lead, orpiment yellow and verdigris green, with the odd dog's head biting its own tail.

Knotwork grows those pages from a seed. It's the most rule-bound piece I've made so far, and it turned out the monks had done most of the thinking already.

The lindisfarne preset. Seed 698, the year Eadfrith became bishop and, so the story goes, started painting.

Over, under, over, under

If you look closely at the back of a Lindisfarne page you can still find the prick marks and the ruled grid. Interlace was laid out on squares, and once you see that, the rule is short.

Take a grid of squares. Every edge has a midpoint. A strand runs diagonally from one midpoint to the next, so at every midpoint two strands cross. Do nothing else and you get a plain plait. Then pick some edges and make them breaks: a strand that reaches a break turns back off it instead of crossing. The rim of the panel is all breaks, so every strand closes up on itself. Breaks are what turn a plait into a knot, and I chose them by the panel's mirrors so the page stays symmetric, often in runs of two or three along a line, which is where the knot's sharp turns come from.

The same six by seven grid. On the left, no breaks, one plait. On the right, three in ten interior edges are breaks.

The bit I was pleased about is over and under. In Çini the strapwork walks each strand from end to end and flips over and under at every crossing it meets. Here there's no walking at all. A crossing on a horizontal edge takes the rising strand over and a crossing on a vertical edge takes the falling one. Every step along a strand lands on the other kind of edge, and every bounce off a break flips its direction, so the alternation round every strand is guaranteed by the grid. In code it's one line:

const over = ((x & 1) === 1) === (dx * dy > 0);

x is in doubled coordinates, where an odd x means a horizontal edge. That's the whole of the weave.

Points in the corners

My first corners were round, and they looked wrong in a way I couldn't name until I went back to the facsimiles. Where a strand turns in a corner of the panel, the scribes draw it up to a sharp point aimed into the corner and back out again. So the page does that now. There's also a "pointed" setting that sharpens every bounce off the rim, which I use for the Kells preset.

Round, corners, pointed. Same knot, three ways to turn at the edge.

The cross-carpet page in the first picture comes from letting a knot fill any region of squares, not just a rectangle. The cross is a plus of knotwork painted on a coloured ground inside a ruled channel, and a second knot fills the bare vellum around it. Then come the frame, its two rules and the red-lead dots. Lindisfarne has a page with over ten thousand of those dots on it, which is the sort of thing that makes you put the pen down for a minute.

The beasts

Insular strands don't always close. Sometimes a ribbon ends in a head, and the head bites something, usually another ribbon or its own tail. On the grid that's a third kind of edge, a cut, where the strand stops instead of turning. Two strand ends always arrive at a cut from the same side, so they pair up neatly: one gets a head, the other becomes the tail it bites.

The head was the problem. I drew mine from curves the way I'd drawn the first lions for Leonor, and it came out like this.

My drawn head. The question it got was "what is this meant to be?", which was fair.

So I did what fixed the lions. I asked an image model for a flat drawing of an Insular hound's head, one gold fill with an even black outline, a red eye, and a piece of blue ribbon gripped in its jaws so I'd know where the bitten strand goes. The neck was to come in from the left as a straight band, cut square, so I could bolt it onto a strand.

The drawing I traced. The blue ribbon hanging below the jaw was cut away first, and the bit inside the mouth kept.

The tracer is the forty lines of Node from the heraldry post. I erased the ribbon below the jaw before tracing and kept the piece inside the mouth, which now gets painted in the tail's colour. The rest was placement. My first go pointed the head straight on along its strand, and every beast stuck out of the knot like a dog through a fence. The version that works lets the neck turn off the strand and narrow, so the head lies along the cut facing its tail, and the tail hooks round under the jaw and up into the mouth.

The kells preset, close up. Four hounds, each with a tail in its mouth.

Two heads on neighbouring cuts sat on top of each other and looked like a scrum, so no cut is allowed beside another now. A mirror copy that would collide just stays a plain break. The heads are still big for the grid and lie over a strand or two, and at very high zoom there's a faint seam where the neck meets the traced head. I can live with both.

Before the painter

My favourite preset has no colour at all. It's the page as the scribe would have left it for the painter: ink on vellum, ruled frame, a few hounds along the rims.

The drawing preset. Ink only.

The lichfield preset, seed 730, the colour gone soft the way that book's has.

In the package

The knots now live in azulejeria as their own module, next to the tile engine but not using any of it. It draws on any 2D canvas.

npm install azulejeria

import { buildKnot, paintKnot } from 'azulejeria/knots';

The README covers the options: masks for crosses and fields, symmetry, cuts, bends, and the traced head with its narrow neck. The knot's grid is the same one under the Mudéjar lacería, so I'd like to see somebody use it for that. Next on the list is Sutton Hoo, which is garnets set in gold cells, and Alicatado's cutter will do most of that work.

Heraldry by Rule

stepinto.dev — Sat, 24 Oct 2026 08:57:06 +0000

The man who boarded at Gatwick never got off in Seville.

Teleporter

Until now the art pages have stayed on the peninsula: Islamic stars, Talavera cobalt, the Alhambra's cut tile, Barcelona's cement floors, Roman pavements under Seville. I'm English, and I wanted the series to come home without changing the subject. The link turns out to be seven hundred years old and made of exactly the right stuff. Eleanor of Castile married Edward I in 1254 and brought her arms with her, the castle of Castile quartered with the lion of León. They're carved on her tomb in Westminster Abbey and on the crosses Edward put up wherever her coffin rested on the way to London. Two centuries later Catherine of Aragon's badge, the pomegranate of Granada beside the Tudor rose, got carved and painted over half of Tudor England. Heraldry is how Spain got into English stone, so heraldry is how England gets into this series.

Those of you who know me, or regular visitors, will maybe know of my deep love for Spain, my friends there and from there, and my dreams, intact and in ruins. Anyway. I wanted to bring this series home, and there are a few more steps I'll flesh out on the way.

Leonor is that page. The shield in the middle is hers, or what hers would have looked like on a wall at Westminster: England impaling Castile and León.

The hall. Every shield but the centre one is a random legal blazon, generated from its position on the wall.

A sentence that paints

A blazon is a sentence that describes a shield exactly, in a grammar that hasn't really moved since the thirteenth century. "Gules three lions passant guardant in pale Or armed and langued Azure" is England. Read it in order: a red field, three lions walking and looking at you, one above another, gold, with blue claws and tongues. Every word changes the picture, and two heralds handed the same sentence paint the same shield, which I rather love.

So the page just has to read the sentence. The parser is a recursive descent over a chunk of the grammar: a field, which is a tincture, a division (per pale, per fess, quarterly) or a variation (barry, paly, chequy, lozengy); then ordinaries (chief, fess, pale, bend, chevron, cross, saltire, bordure, pile, canton), each of which can carry charges of its own; then charges by number and arrangement, with their attitudes and the tinctures of their parts; then marshalling, which is impaling and quartering, which recurse back into the whole thing.

function field() {
  if (peek() === 'per' && DIVISIONS[peek(1)]) {
    take(); const kind = DIVISIONS[take()];
    const a = tincture(); if (peek() === 'and') take(); const b = tincture();
    return { kind, a: a || 'argent', b: b || 'gules' };
  }
  if (peek() in VARIATIONS) {
    const kind = VARIATIONS[take()]; let n = 6;
    if (peek() === 'of') { take(); n = NUMBERS[peek()] || parseInt(peek(), 10) || 6; take(); }
    const a = tincture(); if (peek() === 'and') take(); const b = tincture();
    return { kind, n, a: a || 'argent', b: b || 'gules' };
  }
  return { kind: 'plain', a: tincture() || 'argent' };
}

It's a lot more forgiving than a herald would be. Unknown words are skipped, a missing tincture defaults, "gardant" and "guardant" both work. The sentence is the shareable thing: ?blazon=Or a lion rampant Gules is Scotland, and whatever you type into the box becomes the URL.

The generator goes the other way. Every shield in the hall apart from the centre one is a sentence written by a seeded random generator that knows the rule of tincture (metal on colour, colour on metal, never gold on silver or red on blue). It picks a field, then an ordinary, an ordinary with charges on it, a single charge, or three, and writes it out properly with the capitals in the right places. Then it hands the sentence to the same parser you'd type into. The generator can't paint at all. It can only write, which keeps the hall honest.

The Castile preset on dressed stone. The hall's palette is the medieval one: Or, Argent, Gules, Azure, Sable, Vert and Purpure, and nothing else.

Enamel and gilt

The material is a painted board. Each tincture goes down flat and then gets whatever that pigment would have had. Gold gets a gradient from leaf to shadow and back, and over it a tooled grain, fine diagonal lines punched into the leaf. Silver gets a cool fall-off from top to bottom. The whole shield gets a gloss across it, light at the top left and a touch of dark in the base, and then a black line round the heater shape with a pale line just inside it for the bevel. The shield casts a shadow on the panelling. The oak itself is boards with a grain, and there are stone and red velvet halls for when the oak gets too brown.

The charges are painted like the tinctures, plus one thing. Every charge gets a single outline round the whole of itself, stroked wide in black before the parts are filled, so a lion built from a body and a tail and a leg reads as one animal. That was the theory, anyway.

The lions were toys

I drew the first lions from parts. A body polygon, a tail polygon, a raised leg on top, a scalloped mane, little triangle claws, dot eyes. An afternoon of nudging coordinates got me this.

The first lions. England's three should be the thing you recognise first, and they weren't.

A heraldic lion is a particular drawing. Tufted mane, tail curling up over the back into a brush, tongue out, claws splayed, and for passant guardant the head turned full-face so you see both eyes. You can't write that down as a rule and get a lion out. It's a convention copied by hand from roll to roll since the 1250s, and the honest way to get it is to copy a drawing too.

So I asked an image model for one. The prompt was about what I needed to trace, not what I wanted to look at: a flat vector illustration, one solid gold fill, a thick even black outline around every part, red tongue, blue claws, no shading, no texture, white background. It gave me a lion that a thirteenth-century herald would have recognised, and a purple rampant one to match, and then a pomegranate and a castle on the same terms.

The tracing is forty lines of Node, and it's pretty dumb. Every pixel is classed by its nearest colour out of white, black, gold, red, blue and green. Each class becomes a mask, each mask becomes closed loops by walking the boundary edges between a pixel that is in and a pixel that is out, each loop is simplified with Douglas-Peucker to a tolerance of two and a half pixels, and the points are normalised to the silhouette's bounding box. The silhouette is one layer. Each colour is a layer. The black lines are a layer. The page fills them in that order:

function traced(T, roles) {
  const P = [{ path: loops(T.main), role: 'main' }];
  for (const k of ['red', 'blue', 'green']) if (T[k] && roles[k]) P.push({ path: loops(T[k]), role: roles[k], detail: true });
  P.push({ path: loops(T.sable), role: 'sable', detail: true });
  P.traced = true;
  return P;
}

const DRAW = {
  lion(ch) { return traced(ch.attitude === 'rampant' ? TRACED.rampant : TRACED.passant, { red: 'armed', blue: 'armed' }); },
  pomegranate() { return traced(TRACED.pomegranate, { red: 'seeded', green: 'leaved' }); },
  castle() { return traced(TRACED.castle, { blue: 'armed' }); },
  // ...
};

The colours in the drawing are labels, and the shield doesn't use them. Red in the lion means "armed", and armed resolves to whatever the blazon said, so the same traced lion paints in Or, Purpure, Gules or Sable, with blue claws or red ones. Red in the pomegranate means "seeded" and green means "leaved". The silhouette is filled even-odd so the loop of the tail stays open and the field shows through. The black line network goes on last, and because the drawing's own outline is in it, the page's outline stroke drops to half its width for traced charges so the lion doesn't go muddy at the size of a quarter.

The same blazon, traced. The lions are the drawings; the colours are the sentence's.

It costs about ninety kilobytes of numbers, more than the rest of the page put together, and it was worth every byte. The procedural charges are rules and the lions are a tradition, and if you pretend a tradition is a rule you get a sunburst for a mane.

Argent a pomegranate proper seeded Gules slipped and leaved Vert. Catherine's badge, traced on the same terms as the lions.

Small corrections

Two things got fixed along the way that any herald would have spotted straight off. A crescent has its horns pointing up, to chief; mine pointed down, which is a crescent reversed and a different charge. And charges on a bend lie bendwise, turned with it and sized to the band, rather than standing upright in a column across it.

Argent on a bend Azure three lions rampant Gules. They lie bendwise, as they should.

What comes next

The tower is still drawn from parts and looks it, so it gets the same treatment when there's a drawing. Two of the pieces this page pointed at have since been made. Rosa y Granada is Catherine's rose and pomegranate as a medieval English floor, white clay inlaid in red, with the pomegranate traced here doing double duty. Knotwork is interlace on vellum after Lindisfarne and Kells, the same over-and-under as the Mudéjar lacería, and its beasts' heads came out of the same trace-a-drawing trick as these lions. Sutton Hoo's garnet cloisonné is still in the queue, which is Alicatado's cutter in gold. The English pieces are the same rules in a colder light.

Cut Tile and Poured Cement

stepinto.dev — Fri, 23 Oct 2026 10:16:36 +0000

It was all broken by me really, or built like a clumsy caveman

Trying to have something right afterwards

The two tile walls I wrote up last time are painted: a brush drifts, a wash pools, an ink line goes on top. These two aren't painted at all. Alicatado is cut: every piece is chipped out of a fired, glazed tile with a hammer and bedded in lime next to its neighbours, the way the dados of the Alhambra were made. Hidráulico is pressed: pigmented cement poured into a brass divider, lifted, pressed and left to cure, never fired, the way every hallway in Spain was floored between 1880 and 1960.

I keep asking the same question from different sides. The first two pages were about what a rule looks like once a hand has painted it, and these are about what it looks like once a material has been through it.

The mexuar preset. Octagons and squares underneath, θ at 45 degrees, and every region a piece.

The geometry is borrowed

Alicatado draws nothing new. The pattern comes straight from Çini, which puts a contact point on every edge of a hidden tiling, fires two rays from each at an angle θ, and draws the pattern where the rays collide. Walk the faces of that line web and you have a list of polygons, which Çini colours by class and calls a mosaic.

That was the bit I kept coming back to. Çini's mosaic mode already insets every face a little and calls the gap grout, and its Alhambra palette already cycles glazes by position. It was most of the way to cut tile without ever treating a face as a thing you could pick up. So the new page uses the same polygons, and all the work is in what happens to each one afterwards.

The cutter

A piece on a real alicatado wall is cut by hand to a drawing, and it misses the drawing in four ways. It's set a fraction off where it should be, and turned a fraction. Its corners are nicked. Its long edges bow, because a hammer doesn't cut straight. So every face gets a shift, a turn, a jitter on each vertex and a bow on any edge longer than half a unit, all scaled by a slider called cut, and all drawn from a random generator seeded by the face's position, so the same piece is wrong the same way every time you pan back to it.

Then there's the mortar. Çini shrinks a face towards its centroid to make the joint, which is fine for a square and wrong for a star. Scaling a star towards its centre moves the points a long way and the inner corners hardly at all, so the mortar is wide at the tips and thin in the notches. A real joint is the same width everywhere. The fix is a mitred offset: at each vertex, move inward along the bisector of the two edge normals by the joint width over the cosine of the half angle, clamped so a very sharp point can't shoot off to infinity.

function offsetPoly(poly, d) {
  const n = poly.length, out = [];
  for (let i = 0; i < n; i++) {
    const p = poly[(i + n - 1) % n], v = poly[i], q = poly[(i + 1) % n];
    // unit edge directions, then their inward normals (the polygon is CCW)
    let e1x = v[0] - p[0], e1y = v[1] - p[1], l1 = Math.hypot(e1x, e1y) || 1;
    let e2x = q[0] - v[0], e2y = q[1] - v[1], l2 = Math.hypot(e2x, e2y) || 1;
    e1x /= l1; e1y /= l1; e2x /= l2; e2y /= l2;
    const n1x = -e1y, n1y = e1x, n2x = -e2y, n2y = e2x;
    let bx = n1x + n2x, by = n1y + n2y, bl = Math.hypot(bx, by);
    if (bl < 1e-6) { bx = n1x; by = n1y; bl = 1; }
    bx /= bl; by /= bl;
    const cosHalf = bx * n1x + by * n1y;
    const m = Math.min(d / Math.max(cosHalf, 0.2), Math.min(l1, l2) * 0.49);
    out.push([v[0] + bx * m, v[1] + by * m]);
  }
  return out;
}

That's the whole cutter, twenty lines, and it's what makes a twelve-point wheel look set into a wall rather than drawn on one.

Each piece came from a different tile

The pieces of a cut-tile wall were chipped from many tiles, fired in many batches, so no two are quite the same colour. Every piece shifts its hue, saturation and lightness a touch from its class colour. On top of that goes a mottle, a soft radial cloud of the same glaze darker or lighter where it ran thick. Then the lustre: a glazed surface is glossy, so each piece gets a small highlight on the side nearer the light, with the light's direction on a slider.

The pieces also stand proud of the mortar, and the edges are what sell that. For each side of the inset polygon, take its outward normal and dot it with the light direction. Facing the light, stroke a thin pale line; facing away, a thin dark one, with the alpha scaled by the dot product. Nothing is actually raised, but at reading distance the wall has relief, and if you drag the light slider round the relief moves the way it should.

Close, with wear on. The crazing is in the white glaze, where it shows. The missing piece shows the bed, combed by a trowel, with a shadow cast onto it by the pieces still standing.

Wear is the last layer, and I got it wrong the first time. A missing piece was a flat patch of mortar colour and a repaired piece was a random glaze from the palette, and both read as mistakes rather than history. Now a missing piece is sunk: darker, grainy, combed, with a shadow along the edges that face the light. A repair keeps its own colour and just looks newer, a touch brighter and glassier, with no crazing. The crazing itself only goes on about a third of the pieces, which is enough.

The pajarita

The Alhambra's most famous alicatado isn't a star pattern at all. It's the pajarita, the wall of birds, hexagons and stars in the p3 symmetry group with no mirrors, so every bird is the same hand. Çini draws it directly, with one S-shaped Bézier curve splitting every rhombus into two crescents. For Alicatado I sample each curve into ten points, so a crescent is a polygon like everything else and goes through the same cutter. The hexagons and stars sit over the birds, so they paint their own mortar first: a wide stroke of lime around the piece, then the inset fill on top.

Pajaritos. Every curve is a polygon now, and every bird a piece.

Then cement

Hidráulico is the opposite kind of page. Alicatado used none of the azulejeria engine and Hidráulico uses all of it, exactly as Azulejería and Jerez do. The only thing that changes is what the tile is made of.

A cement tile isn't painted, so there's no wash and no ink line. The pigment goes into a brass divider and comes out flat, matte, and butted straight against the next colour with no outline between them. The divider is metal, so edges are straight. The only hand in it is the bleed: a fraction of a millimetre where one pigment crept under the divider before it lifted. The surface is cement, so it has grain and cures a little unevenly. It doesn't craze, but it wears, and it wears where people walk.

So the engine now takes a material, an object of optional hooks that change what the tile is made of without touching what is drawn on it:

const material = {
  ampOf: hand => 0.0015 * hand,            // the mould is brass; the hand is only bleed
  shape(g, pts, col, b) {                  // flat fill, then the pigment that crept under
    trace(g, pts, true);
    g.fillStyle = col; g.fill();
    const bleed = b.amp * 7;
    if (bleed > 0.0005) {
      g.strokeStyle = col; g.lineWidth = bleed * (0.6 + 0.8 * b.rng());
      g.globalAlpha = 0.35; g.stroke(); g.globalAlpha = 1;
    }
  },
  surface(g, S, pal, rng) { /* grain, and the cast of an uneven cure */ },
  plain(g, S, pal, rng) { /* a checker's plain tile is solid pigment */ },
  lay: { shift: 0.004, turn: 0.003 },      // laid tight, machine square
  gapOf: S => Math.max(0.8, S * 0.01),     // a hairline joint
  age(ctx, t) {                            // the pigment dulls along the line people walk
    const walk = Math.exp(-((t.cy / (t.S * 2.6)) ** 2));
    const w = 0.05 + 0.85 * walk + (t.rng() - 0.5) * 0.12;
    ctx.fillStyle = hexA(t.pal.glaze, Math.min(0.6, w * 0.6));
    ctx.fillRect(-t.s / 2, -t.s / 2, t.s, t.s);
    // then scuffs, the odd crack, a corner chipped to the grey beneath
  },
};

shape, line and dot replace the brush's strokes. surface lays the ground, plain paints the tile a checker alternates with, lay is how far a tile strays from its cell, gapOf is the joint, and age is drawn over each tile in its own frame when age is on, with the tile's world position passed in so wear can follow a line through the floor rather than a line through the screen. Without a material, every hook falls back to the glazed behaviour.

The zaguán preset. Flat burgundy and grey, straight edges, and a joint you can barely see.

Bodega, with wear on. The paler band through the middle is the walked line.

The design never finds out. None of the hooks read the design's random generator, so a material can't move a motif, and the old walls are untouched by construction. I checked anyway: I hashed the canvas bytes of every Azulejería and Jerez preset, two query-string walls with age and checker on, and every thumbnail in every panel, before and after the change, and all twenty-two were identical. The package is at 1.1.0 and the README has the hooks.

Casino. Every tile whole, the star at its centre, and a second star made by four corners.

What the two pages taught the engine

Alicatado is the more interesting of the two for the package, because it doesn't use it and still ended up rewriting half of it. Not the tile half: the drag, the pinch, the wheel, the double tap, the buffered repaint that lets you pan without recomputing the world, the panel with its tabs and thumbnails, the query string, the seeded random and the colour helpers. All of that is the same on every page, and Alicatado has its own copy because the engine only offers it bundled with a grid of square tiles.

So the next version of the engine draws its line somewhere else. A viewer: a canvas you paint a world into, with all the interaction and the panel. And on top of it, a tile wall, which is one paint function and the materials. Alicatado becomes the viewer plus its own paint function. So would a trencadís page, or a Roman mosaic, which is where the cutter would get reused. That's a breaking change, so I waited until there were three materials to design it against instead of one.

The fez preset. Small pieces, dark ground, the mortar doing most of the drawing.

Tiles Painted by Rule

stepinto.dev — Thu, 22 Oct 2026 11:07:51 +0000

The roses and white lilies, their petals curl and tap the azulejería,
The sounds of a future unrealised.

Sounds of a Future Unrealised

Two of the art pages here are walls of tin-glazed tiles. Azulejería is the cobalt rosette of a Talavera dado and the strapwork of a Seville patio. Jerez is the same wall sent south: grapes and vine leaves, horses' heads, a sherry glass sitting across every join. Neither page has a picture in it. Each grows a design from a seed and paints it the way a brush would, then keeps repeating it until the screen is full.

Design number 71, cobalt on white. Every tile is a quarter of the flower.

Jerez started life as Azulejería with the motifs swapped, and by the time it worked the two files shared about six hundred lines. So I pulled the shared part out into a package.

npm install azulejeria

Here's how the wall gets made, and what I had to change to pull the engine out from under the motifs.

One square, mirrored across its diagonal

The módulo, the four-tile repeat every Andalusian dado is laid in, is a pattern that only completes where four tiles meet. The tile on its own is a quarter of a flower, a quarter of a star, and the wall supplies the rest by laying each neighbour mirrored. The whole design lives in one unit square, and the trick only works because that square is symmetric across its diagonal. Swap x and y and you get the same picture.

Corner (0,0) holds the main motif. Corner (1,1) holds a small one. The midpoint of each edge holds half of something, so the tile next door finishes it. A leaf or a strap runs up the diagonal, which is its own mirror. Everything else is placed in pairs, at (x,y) and (y,x).

With that one constraint the same list of elements serves four repeats:

Module, mirrored. The design fills the tile with its main corner at bottom right. Odd columns are flipped left to right, odd rows top to bottom, so four tiles make one great rosette, and the far corners make a smaller one between them.
Module, turned. Same tile, rotated by quarter turns instead of flipped. The motif completes the same way, but the brush strokes now run in four directions, which reads less like a stamp.
Single. The design is laid four times inside one tile, mirrored about its centre, so every tile carries the whole motif. The motif is drawn at 1.35 times the size to fill it.
Checker. Single tiles alternate with plain ones, a ring and four dots in the middle, the way an ajedrezado floor does.

The same design five ways. On the left, one tile alone, with the rosette's corner at bottom right. Then mirrored, turned, every tile whole, and checkered with plain ones.

When the page grows a design it has no idea which repeat you'll ask for, and it doesn't need one.

Growing a design from a seed

A design is a list of elements, and each element names a painter and carries its parameters. The seed feeds a small deterministic random generator (mulberry32, thirty lines, good enough), and a motif function reads from it in a fixed order. The same seed always grows the same design, so ?seed=4242 is a wall you can send to someone.

This is the rosette, as the Azulejería page defines it:

flora({ rng, density, bands, bold, pick, role, dots }) {
  const els = [];
  const n = 2 + Math.floor(rng() * 3);
  els.push({ t: 'rosette', n, rIn: (0.07 + rng() * 0.05) * bold, rOut: (0.26 + rng() * 0.14) * bold,
             wd: 0.5 + rng() * 0.5, rings: 1 + Math.floor(rng() * 2), scallop: rng() < 0.55, ...role() });
  if (density >= 2) els.push({ t: 'bud', r: (0.1 + rng() * 0.1) * bold, n: 2 + Math.floor(rng() * 2), ...role() });
  if (density >= 3) els.push({ t: 'half', r: (0.09 + rng() * 0.08) * bold, n: 3, ...role() });
  if (density >= 3) els.push({ t: 'leaf', r0: 0.42 * bold + rng() * 0.08, r1: 0.7 * bold + rng() * 0.12, wd: 0.5 + rng() * 0.5, role: 'wash' });
  if (bands) els.push({ t: 'band', kind: pick(['circle', 'diamond', 'circle']), w: 0.035 + rng() * 0.03, ...role() });
  if (density >= 4) els.push({ t: 'ring', r: 0.5 * bold + rng() * 0.08, lobes: 5 + Math.floor(rng() * 4) });
  if (density >= 5) els.push(dots(3, 4, 0.55, 0.4, 0.85));
  return els;
}

The density slider is just how far down that list you get to go. One is the rosette alone. Five adds a scalloped ring and a scatter of dots in the spare space. role() decides whether an element is painted in the main wash or in one of the palette's accents, and a palette with no accents gets everything in cobalt, which is how a cobalt-only palette stays blue and white while Seville goes polychrome from the same motif.

Design number 71 at density one to five. Nothing moves, the list just gets longer.

The Jerez motifs are the same thing with different nouns. The horse motif starts with two heads, adds a horseshoe near the far corner (so four cluster at every grout crossing), then a feria cockade half on each edge, then reins as a lattice. The bodega motif crosses two venencias at the corner and lies a bota up the diagonal.

The three Jerez motifs as whole tiles: viña, caballo, bodega. Same corners, same edges, different nouns.

You can smell fino just looking at those generated azulejos.

Juanka

Painting like a hand

Draw a design with clean arcs and straight lines and you get clip art. The pages look painted because every line drifts.

The drift is a wobble function: two sines of different pitch and random phase, summed, applied along the normal of whatever is being drawn. An arc becomes a polyline whose radius breathes a little as it goes round. A straight line bows. A petal gets a different wobble on each side so it is never quite symmetric. The hand slider scales the amplitude. At zero the brush turns into a plotter.

Hand at zero, a half and one. Same seed, same design, and the brush gets less sure of itself.

Colour goes on the way a glaze does. A wash is filled at about half opacity, then filled again shifted by a hair at a fifth opacity, so the colour pools at one edge of every shape. The ink line on top varies its width by up to twenty percent per stroke. Under all of it the tile's white is three soft radial blooms of the palette's tint colour, placed by the tile's own seed, with a faint darker rim where a real glaze thickens at the edge.

Then the wall adds its own imperfection. Each cell of the grid hashes its position with the seed and uses that to pick one of four painted variants of the tile, nudge it by up to one and a half percent of its width, and turn it by up to a degree. Switch on age and half the tiles get a warm cast, a fifth get a craze line or two, and one in twenty loses a corner to the grout.

The oloroso preset with age on. The crazing and the warm cast are the wall's doing, not the tile's.

The wall

Tiles are expensive to paint and cheap to draw, so each one gets painted once into an offscreen canvas at the current zoom and the wall is just drawImage in a loop. Four variants of the painted tile, three of the plain one for checker, and the hash decides which goes where. Pan is a translation. Zoom scales the cached tiles immediately so it feels live, then repaints them at the new size once the wheel has been still for a sixth of a second.

Double-tap picks a new seed. A design number shows in the panel so you can find it again.

Pulling the engine out

When I laid the two files side by side the shared part was obvious: the random generator, every geometry helper, the ink and wash strokes, the tile painter, the wall renderer, the pointer handling, and the panel wiring with its tabs, thumbnails, sliders and query string. What differed was the palettes, the motif functions, the painters those motifs name, the presets, and the colours of the panel.

So that's where the package draws its line. createWall(canvas, { palettes, motifs, painters, presets }) is the engine. A motif is a function of the seeded context that returns elements. A painter is a function of an element and a brush:

bud(el, b) {
  const { g, pal, lw, amp, rng, col, Q } = b;
  for (let k = 0; k < el.n; k++)
    b.petal(1, 1, Math.PI + (k + 0.5) * Q / el.n, 0.02, el.r, 0.8, col);
  ink(g, arcPts(1, 1, el.r + 0.035, Math.PI, Math.PI + Q, amp, rng, 16), lw * 0.8, pal, rng, false);
}

The brush carries the scaled canvas context, the palette, the line weight, the wobble amplitude, the design's random generator, the colour the element's role resolved to, and the strokes every motif reaches for: petal, kite, shape (wash then ink), dot, lobes. Four painters ship with the engine because both pages used them unchanged: the band across the far corner, the scalloped ring, the lattice line, the dots. Everything else, from the horse's head (a nineteen-point polygon traced once and placed twice) to the half catavino whose stem runs along the tile edge, stays in the page that owns it.

The panel's CSS went the same way. The two pages' stylesheets differed in fourteen colour values and nothing else, so the package ships the stylesheet with custom properties and each page sets a dozen of them.

I was most careful about the random generator's call order. A painter that reads rng() one extra time shifts every wobble after it, and the wall for seed 71 is no longer the wall for seed 71. So I checked the refactor at the pixel. I rendered every preset on both pages before and after, plus a couple of query-string walls with age and checker on, and every thumbnail in every panel, and compared the canvas bytes. All identical. The pages look exactly as they did, and for a refactor of an art piece that's the only result I'd accept.

Serving the same file twice

The pages import the engine from /art/lib/azulejeria.js. That path is a Hugo mount of the package's source directory, so the art pages run the same file npm ships. There's no build step because there's nothing to build: one ES module, one stylesheet, no dependencies.

If you fancy a wall of your own, the README has a forty-line example, and the two pages are the long versions. The motifs are the fun bit to write. Mine are a Talavera rosette, Mudéjar strapwork, a vine, a horse and a bodega, and I would rather like to see what someone else's corner of the world looks like as a quarter tile.

The cartujano preset. Eight heads around a point, four shoes at every crossing, and not one of them drawn by hand.

The Hot Path to Claude Is a Shell Script

stepinto.dev — Thu, 22 Oct 2026 07:35:54 +0000

The hot path to Claude is one HTTPS POST and a stream of six event types. Every SDK wraps that in thousands of lines, and the wrapping costs you: in cold start, in memory, and in the milliseconds between the model finishing a thought and your code acting on it. For a chat window none of that matters. For a CLI that should feel instant, a Lambda that is billed from the first millisecond, or an agent loop making ten thousand calls a day, it is the only part of the latency you control.

This series writes the path by hand, one language a week, one file each, and measures what each one adds. This post is the floor: a complete client in bash and curl, in one file, with no jq, that streams the reply as it arrives, completes a tool call round trip, and reports API errors properly. Everything that follows is measured against it, and against the official SDKs.

The code and the harness are at github.com/AndyCross/claude-hot-path, and the leaderboard lives at /claude-hot-path/.

The spec

Every client in the series has to pass the same seven points, and a harness checks them rather than me reading the code.

Read the key from ANTHROPIC_API_KEY and the base URL from ANTHROPIC_BASE_URL. Nothing else from the environment.
Read the prompt from stdin.
POST /v1/messages with the x-api-key, anthropic-version: 2023-06-01 and content-type: application/json headers, and a body with model, max_tokens, stream: true, messages and tools.
Print each text_delta as it arrives. The harness checks that the first visible byte reached stdout before the mock finished sending the stream, so buffering the reply, or flushing only on newlines, fails.
Declare one tool, local_time, which takes an IANA timezone. When the stream ends with stop_reason: "tool_use", assemble the input_json_delta fragments, run the tool, send the tool_result back in a second request with the assistant turn echoed, and stream that reply too.
On a non-2xx response, print the body's error.message to stderr and exit non-zero.
One source file. HTTP and TLS from the platform where it has them. Where it does not (C, Zig), one named library, which counts towards size.

Point 5 is the one that separates a client from a curl wrapper. Tool use is where the protocol stops being request and response and becomes a conversation you have to maintain, and the tool's arguments arrive as fragments of JSON that you assemble yourself.

What comes down the wire

With stream: true the response is text/event-stream. Each event is an event: line, a data: line carrying JSON, and a blank line. Here is the shape of the first turn, from a real recording, trimmed:

event: message_start
data: {"type":"message_start","message":{"id":"msg_...","model":"claude-opus-5-5",...}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"tool_use","id":"toolu_...","name":"local_time","input":{}}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"input_json_delta","partial_json":"{\"timezone\""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"input_json_delta","partial_json":": \"Europe/London\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use"},"usage":{"output_tokens":56}}

event: message_stop
data: {"type":"message_stop"}

Two things I had wrong before I recorded it. The model went straight to the tool call with no preamble text, so a client that assumes a text block always comes first is wrong. And there is a ping event in the middle that the documentation mentions and nobody's mental model includes. A client has to ignore event types it does not know.

The six you act on are message_start, content_block_start, content_block_delta, content_block_stop, message_delta and message_stop. Deltas come in two kinds, text_delta with a text field and input_json_delta with a partial_json field, and the index says which content block they belong to.

The client

The whole thing is 93 lines. The interesting parts follow, and the rest is in the repo.

JSON without jq means encoding strings yourself. The prompt comes from stdin and could contain anything, so backslash, quote and the control characters have to be escaped:

json_str() {
  local s=$1
  s=${s//\\/\\\\}; s=${s//\"/\\\"}
  s=${s//$'\n'/\\n}; s=${s//$'\r'/\\r}; s=${s//$'\t'/\\t}
  printf '"%s"' "$s"
}

Decoding goes the other way. The text deltas arrive as JSON strings, escapes and all, and bash's printf '%b' happens to understand \n, \t, \\ and \uXXXX, so after swapping \" for " you can hand it the string:

json_unstr() {
  local s=$1
  s=${s//\\\"/\"}; s=${s//\\\//\/}
  printf '%b' "$s"
}

That \uXXXX support needs a UTF-8 locale. In a slim Debian image there is none set, printf prints the escape literally, and "café" comes out as caf\u00E9. The Dockerfile sets LC_ALL=C.UTF-8 and that is the kind of thing this series is for.

The stream loop is curl with -N to turn off its output buffering, read line by line, and a regex per event type:

while IFS= read -r line || [[ -n $line ]]; do
  [[ $line == data:* ]] || { [[ $line == event:* || -z $line ]] || errbody+="$line"; continue; }
  data=${line#data: }
  if [[ $data =~ \"type\":\"text_delta\",\"text\":\"((\\.|[^\"\\])*)\" ]]; then
    text=$(json_unstr "${BASH_REMATCH[1]}"; printf x); text=${text%x}
    printf '%s' "$text"; ASSISTANT_TEXT+="$text"
  elif [[ $data =~ \"type\":\"input_json_delta\",\"partial_json\":\"((\\.|[^\"\\])*)\" ]]; then
    TOOL_INPUT+=$(json_unstr "${BASH_REMATCH[1]}")
  elif [[ $data =~ \"type\":\"tool_use\",\"id\":\"([^\"]+)\",\"name\":\"([^\"]+)\" ]]; then
    TOOL_ID=${BASH_REMATCH[1]}; TOOL_NAME=${BASH_REMATCH[2]}
  elif [[ $data =~ \"stop_reason\":\"([a-z_]+)\" ]]; then
    STOP_REASON=${BASH_REMATCH[1]}
  fi
done < <(curl -sS -N -D "$hdr" "$BASE/v1/messages" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    --data-binary "$body")

The || [[ -n $line ]] on the read is there because an error response is a single JSON line with no trailing newline, and read returns false on the last line of a file that lacks one, so without it the loop body never ran for the only line that mattered. Lines that are not data:, event: or blank are collected as the error body, and after the loop the status code comes out of the headers file curl wrote with -D.

The regex is doing the job a JSON parser would. It works because the API emits compact JSON with the keys in a known order, and that is the honest caveat: a bash client is parsing a wire format with pattern matching, and the first time the server reorders two keys it breaks. Every other client in the series uses a real parser. This one is the floor, and it is meant to be.

When the first stream ends with tool_use, the client runs the tool with TZ="$timezone" date, builds the assistant turn back out of what it collected (any text, then the tool_use block with its assembled input) and sends the three-message conversation as a second request. The reply to that is the answer.

What it measures as

The harness runs every client in its own container against a mock that replays the recorded exchange with the original gaps between chunks. Nothing is measured over the network. The one real call per client is for conformance, and no timing from it is published.

	bash and curl
Artefact	3.7 KB (the script)
Runtime	23.7 MB (bash, curl, and every shared library they link)
Cold start, median of 100	7.0 ms
Turnaround, median of 100	19.1 ms
Client total, median of 100	35.3 ms
Peak RSS	11 MB
Lines of code	75

Apple M4 Max under Docker, linux/arm64, bash 5.2.37, curl 8.14.1 with OpenSSL 3.5.7.

Cold start is process spawn to the mock receiving the first request. Turnaround is the first reply finishing to the second request arriving, which is the client parsing the stream, running the tool and sending again. Client total adds the tail after the last reply, so it is every millisecond the mock was not streaming. All three are differences between timestamps the mock recorded and the runner's spawn and exit, with nothing subtracted. The runtime figure counts the shared libraries because a static binary pays for its TLS and HTTP inside itself, and a dynamically linked curl should pay for libcurl and OpenSSL the same way. Without them bash would show 1.7 MB and win on a technicality.

Thirty-five milliseconds of client time for two requests is two curl process spawns, a date process, and a few hundred regex matches in a shell loop. Nineteen of those milliseconds are the turnaround alone. The Go and C# clients that follow do the same work in under a quarter of that, and the interesting question for the rest of the series is whether anything gets much below what Go does, or much smaller than what a Native AOT .NET binary does. I have an opinion about both and the leaderboard will tell me whether it was right.

The thing to beat

Every row on the leaderboard is measured against the official SDK as well as against the other hand-written clients. The SDK rows sit below a line on the board and are not ranked, because they are the reference rather than entries. The first is the Python SDK, anthropic 1.15.0 on Python 3.14, written the way its documentation says: messages.stream(), text_stream, get_final_message(), and the manual tool loop from its own tool-use page. Fifty-five lines, which is the shortest client on the board, and the slowest by a wide margin. Next to it, so the cost of Python and the cost of the SDK can be told apart, is a client in one Python file on http.client and json.

	bash and curl	Python, standard library	Python SDK
On the path, median of 100	35.3 ms	140.4 ms	592.5 ms
Cold start	7.0 ms	123.8 ms	464.6 ms
Turnaround	19.1 ms	1.9 ms	8.7 ms
Tail after the last reply	9.2 ms	15.2 ms	119.8 ms
Peak RSS	11 MB	21 MB	84 MB
Runtime shipped	23.7 MB	35.5 MB	71.9 MB

Python itself costs 140 ms per process, almost all of it the interpreter starting and importing four standard modules. The SDK costs 450 ms on top: pydantic, httpx, anyio and the generated types on the way in, and the HTTP client's pool and the interpreter tearing all of that down on the way out, after the answer has already been printed. In between, while the stream is actually flowing, the SDK is quick. If your process lives for an hour, none of this is a number you would notice. If it lives for one call, it is half a second every time, and that is what this series is about. The Python post has both clients in full.

How to run it

git clone https://github.com/AndyCross/claude-hot-path
cd claude-hot-path
./bench/bench.sh bash

You need Docker and Python 3 and you do not need a key. The fixtures in the repo are real recordings. If you want to re-record them, ./bench/bench.sh record bash runs one exchange through a proxy that reads your key from the shell and never writes it anywhere, and the client under test is handed a placeholder.

Adding a language is a directory with the source file, a Dockerfile and a four-line meta.env, and the CI runs the bench on every pull request. If you want to see your language on the leaderboard before I get to it, that is the way.

The Danger of a Hidden Sun

stepinto.dev — Tue, 20 Oct 2026 11:15:50 +0000

I spent a weekend trying to make a 3D scene look less flat and ended up making it faster instead. The flatness and the frame drops turned out to be the same bug, viewed from opposite sides.

I was helping out a friend on their app. The scene is a few hundred small buildings on a flat ground plane, rendered with Filament through react-native-filament, running on whatever phone the user happens to own. It has a performance budget system with tiers, and the lower tiers get simplified meshes, fewer decorations and smaller render arenas. It is the kind of app where you count draw calls.

What I had not counted was the sun.

An all-emissive pipeline

The models were authored the classic mobile way. Ambient occlusion and colour are baked into one texture per material, and that texture goes in the glTF emissive slot with the base colour set to black. The result is a surface that looks the same from every angle, needs no lights, and is cheap. Artists have done this for years and for good reason. Per-instance tinting works too: you multiply the emissive factor on a material instance and the shared texture picks up the colour.

I checked the material setup across every GLB the app loads, with a short script that reads the JSON chunk out of each binary:

import struct, json, sys
d = open(sys.argv[1], 'rb').read()
length = struct.unpack('<I', d[12:16])[0]
gltf = json.loads(d[20:20 + length])
for m in gltf['materials']:
    pbr = m.get('pbrMetallicRoughness', {})
    print(m['name'],
          'base', pbr.get('baseColorFactor'),
          'emissiveTex' if 'emissiveTexture' in m else '-',
          'unlit' if 'KHR_materials_unlit' in m.get('extensions', {}) else 'lit')

Out of 480 materials, 477 were black base colour plus emissive texture, which is fine. That is the pipeline working as designed.

The last column is the problem. Every one of them said lit.

What a lit material costs when it has nothing to light

Filament's glTF loader picks a shader from the material's declared shading model. A material without the KHR_materials_unlit extension is lit, and the lit "ubershader" does the full job on every fragment: evaluate the directional light, sample the shadow map, look up the indirect light from the environment, run the BRDF. Then it multiplies the diffuse term by the base colour.

The base colour is black. So the fragment shader does all of that work, multiplies it by zero, adds the emissive texture on top, and writes the pixel. It does that every frame, for every covered pixel, on a phone.

And there was a sun. The scene had a directional light at 80,000 lux with shadow casting enabled, because that is what you put in a scene when you set it up, and nobody takes it out. A light that casts shadows makes Filament render a shadow map before the main pass: every caster drawn again from the light's point of view into a depth texture, each time the camera or anything in the scene moves. On a map that scrolls, that is most frames.

Not one pixel showed any of this. Shadows darken the lit diffuse term, which was zero. The indirect light brightens the lit diffuse term, which was zero. The sun was a hidden workload with no output, sitting in the scene like a process you forgot was running.

I had been treating lighting as something I could add later, when the tier budget allowed. The budget was already being spent. The sun was my single biggest "SUPER tier" feature, enabled on the cheapest phones the app supports, and nobody knew it was on.

Finding it from the other direction

I only noticed because I was trying to make things look better. I had seen a lovely three.js scene with shaded, matcap-style buildings and wondered why mine looked like paper cutouts. The honest answer was that nothing in my scene responded to light, so of course it looked flat. Chasing that down meant reading the material JSON above and then rendering the models headlessly with Filament's own gltf_viewer, which ships in the Filament release archive alongside matc and cmgen.

The headless run confirmed it. With the stock materials, shadows on, SSAO on, an environment map loaded, the render was identical to shadows off, SSAO off, no environment. The pipeline had quietly made every lighting feature a no-op, and the lit shader was still running underneath.

It is worth getting into the habit of rendering your assets outside your app with the engine's reference viewer. The viewer has a batch mode that takes a JSON spec and writes screenshots without a window:

gltf_viewer --headless --batch=spec.json --ibl=./sky model.glb

If toggling a feature in that spec changes nothing in the output, you are paying for that feature and getting nothing back.

The one-line fix

// before
<Light type="sun" intensity={80000} castShadows />

// after
<Light type="sun" intensity={80000} />

That removes the shadow map pass. The lit shader still runs, but the second geometry pass is gone. I was sceptical it would be noticeable. It was. On a mid-range Android device the camera flyover went from slightly jerky to smooth, enough that I shipped the change on its own the same day. There was no visual difference, because there was no visual to lose.

If you have a Filament scene with baked, emissive-only materials and a shadow-casting light, go and check. It is a thirty-second fix.

Actually turning the sun off

Removing shadows is the cheap half. The per-fragment lighting maths still runs on the black base colour. To stop that you need the materials declared unlit, so the loader picks the unlit shader.

The obvious move is to add KHR_materials_unlit to the materials in the pipeline. I tried that on one model a while ago and it rendered black, and at the time I shrugged and moved on. Now I know why. In Filament's glTF ubershader source (libs/gltfio/materials/base.mat.in), the entire emissive block sits inside #if !defined(SHADING_MODEL_UNLIT). An unlit glTF material in Filament outputs base colour and nothing else. The emissive slot that the whole pipeline depends on is ignored.

So the transform has to be two steps, not one. Move the texture from the emissive slot to the base colour slot, then flag the material unlit. With gltf-transform it is small:

for (const m of doc.getRoot().listMaterials()) {
  const tex = m.getEmissiveTexture();
  if (!tex) continue;
  m.setBaseColorTexture(tex);
  m.setBaseColorFactor([1, 1, 1, 1]);
  m.setEmissiveTexture(null);
  m.setEmissiveFactor([0, 0, 0]);
  m.setExtension('KHR_materials_unlit', unlit.createUnlit());
}

Per-instance tinting survives this, because the unlit ubershader still has the baseColorFactor parameter and multiplies it in. The runtime code changes from setting a float3 on emissiveFactor to setting a float4 on baseColorFactor. The textures, the instancing and the draw calls are all unchanged.

The part that got me interested

Once the texture is in the base colour slot, the same asset works as a lit material too. Leave the unlit flag off, add a small environment map, and the sun that was doing nothing starts doing something. The buildings cast shadows on each other, the walls read darker than the roofs, and the flatness I set out to fix goes away.

Which means the lighting decision becomes a per-tier flag in the asset build rather than a rewrite. Low tiers get the unlit variant and stop paying for the sun at all. The top tier gets the lit variant and, for the first time, actually gets what it was paying for. The transform is the same function with one boolean.

I have not shipped that half yet. It needs on-device measurements, an exposure pass, and a think about dark mode. But it reframed the whole thing for me. I had assumed lighting was a luxury I could not afford on mobile. It turned out I had been buying it all along and leaving it in the box.

What to check in your own scene

Dump the materials from your GLBs and look for the combination of black base colour, emissive texture and no unlit extension. That is the hidden-sun signature.
If you have a shadow-casting light and no material has a non-black base colour, the shadow map is pure cost. Turn it off today.
If you want to stop the lighting maths entirely, remember that Filament's unlit path drops emissive. Move the texture first, then flag the material.
Render your assets with the engine's reference viewer in batch mode and toggle features. Anything that does not change the output is a candidate for removal, or a sign that you have a feature you are not actually using.

The sun is a budget user like any other. It just does not show up on the invoice unless you go looking.

The Smallest Claude Client Is a Shell Script

stepinto.dev — Sat, 17 Oct 2026 12:48:46 +0000

Every SDK for a language model API is thousands of lines, and that size teaches people that a client is a big thing. It is not. Underneath, the Claude Messages API is one HTTPS POST with a JSON body, and the reply is a stream of Server-Sent Events of which you need to understand six. This post is a complete client in bash and curl, in one file, with no jq. It streams the reply as it arrives, completes a tool call round trip, and reports API errors properly. It is the floor for a series that does the same thing in a different language every Thursday and measures each one against the others.

The code and the harness are at github.com/AndyCross/smallest-client, and the leaderboard lives at /smallest-client/.

The spec

Every client in the series has to pass the same seven points, and a harness checks them rather than me reading the code.

Read the key from ANTHROPIC_API_KEY and the base URL from ANTHROPIC_BASE_URL. Nothing else from the environment.
Read the prompt from stdin.
POST /v1/messages with the x-api-key, anthropic-version: 2023-06-01 and content-type: application/json headers, and a body with model, max_tokens, stream: true, messages and tools.
Print each text_delta as it arrives. Buffering the whole reply and printing it at the end fails.
Declare one tool, local_time, which takes an IANA timezone. When the stream ends with stop_reason: "tool_use", assemble the input_json_delta fragments, run the tool, send the tool_result back in a second request with the assistant turn echoed, and stream that reply too.
On a non-2xx response, print the body's error.message to stderr and exit non-zero.
One source file. HTTP and TLS from the platform where it has them. Where it does not (C, Zig), one named library, which counts towards size.

What comes down the wire

event: message_start
data: {"type":"message_start","message":{"id":"msg_...","model":"claude-opus-5-5",...}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"tool_use","id":"toolu_...","name":"local_time","input":{}}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"input_json_delta","partial_json":"{\"timezone\""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"input_json_delta","partial_json":": \"Europe/London\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use"},"usage":{"output_tokens":56}}

event: message_stop
data: {"type":"message_stop"}

The client

The whole thing is 93 lines. The interesting parts follow, and the rest is in the repo.

JSON without jq means encoding strings yourself. The prompt comes from stdin and could contain anything, so backslash, quote and the control characters have to be escaped:

json_str() {
  local s=$1
  s=${s//\\/\\\\}; s=${s//\"/\\\"}
  s=${s//$'\n'/\\n}; s=${s//$'\r'/\\r}; s=${s//$'\t'/\\t}
  printf '"%s"' "$s"
}

json_unstr() {
  local s=$1
  s=${s//\\\"/\"}; s=${s//\\\//\/}
  printf '%b' "$s"
}

The stream loop is curl with -N to turn off its output buffering, read line by line, and a regex per event type:

while IFS= read -r line || [[ -n $line ]]; do
  [[ $line == data:* ]] || { [[ $line == event:* || -z $line ]] || errbody+="$line"; continue; }
  data=${line#data: }
  if [[ $data =~ \"type\":\"text_delta\",\"text\":\"((\\.|[^\"\\])*)\" ]]; then
    text=$(json_unstr "${BASH_REMATCH[1]}"; printf x); text=${text%x}
    printf '%s' "$text"; ASSISTANT_TEXT+="$text"
  elif [[ $data =~ \"type\":\"input_json_delta\",\"partial_json\":\"((\\.|[^\"\\])*)\" ]]; then
    TOOL_INPUT+=$(json_unstr "${BASH_REMATCH[1]}")
  elif [[ $data =~ \"type\":\"tool_use\",\"id\":\"([^\"]+)\",\"name\":\"([^\"]+)\" ]]; then
    TOOL_ID=${BASH_REMATCH[1]}; TOOL_NAME=${BASH_REMATCH[2]}
  elif [[ $data =~ \"stop_reason\":\"([a-z_]+)\" ]]; then
    STOP_REASON=${BASH_REMATCH[1]}
  fi
done < <(curl -sS -N -D "$hdr" "$BASE/v1/messages" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    --data-binary "$body")

What it measures as

	bash and curl
Artefact	3.7 KB (the script)
Runtime	23.7 MB (bash, curl, and every shared library they link)
Cold start, median of 100	7.1 ms
Overhead, median of 100	56.6 ms
Peak RSS	11 MB

Apple M4 Max under Docker, linux/arm64, bash 5.2.37, curl 8.14.1 with OpenSSL 3.5.7.

Cold start is process spawn to the mock receiving the first request. Overhead is spawn to exit minus the time the mock spent replaying, which is what the client itself cost. The runtime figure counts the shared libraries because a static binary pays for its TLS and HTTP inside itself, and a dynamically linked curl should pay for libcurl and OpenSSL the same way. Without them bash would show 1.7 MB and win on a technicality.

Fifty-seven milliseconds of overhead for two requests is two curl process spawns plus a few hundred regex matches. The Go and C# clients that follow do the same work in under half of that, and the interesting question for the rest of the series is whether anything gets much below what Go does, or much smaller than what a Native AOT .NET binary does. I have an opinion about both and the leaderboard will tell me whether it was right.

How to run it

git clone https://github.com/AndyCross/smallest-client
cd smallest-client
./bench/bench.sh bash

What I Got Wrong About Go

stepinto.dev — Sat, 17 Oct 2026 12:48:42 +0000

The C# to Go series was written against Go 1.22 and 1.23. Go is at 1.27 now and two of those versions are out of support, so this is the Christmas post the landing post promised: the claims in the series that the toolchain has overtaken, each one checked against a current install rather than remembered. Every snippet here was run on go1.27.2.

Container CPU limits arrived in 1.25, not 1.19

The Kubernetes post says "Go respects container resource limits automatically since Go 1.19" and its comparison table repeats it. The 1.19 change was GOMEMLIMIT, which is memory. CPU came much later. The Go 1.25 notes say that on Linux "the runtime considers the CPU bandwidth limit of the cgroup containing the process" and that GOMAXPROCS now defaults to the lower of that limit and the logical CPU count. It also re-reads the limit periodically, so a vertical autoscaler changing the limit under a running pod takes effect without a restart.

Anything older than 1.25 in a container with a CPU limit still needs Uber's automaxprocs, or an explicit GOMAXPROCS in the pod spec. On the toolchain the post was written against, the log line in its example would have printed the node's core count, not the pod's limit.

The image pins are two versions out of support

Every Dockerfile in the containers post starts with golang:1.22, and every job in the GitHub Actions post has go-version: '1.22'. Go supports the two most recent majors, so 1.22 fell out of support when 1.24 shipped in February 2025, and the supported pair as I write is 1.26 and 1.27.

The fix is to stop pinning a minor in two places. The module file already names the version, so let the build read it:

- uses: actions/setup-go@v7
  with:
    go-version-file: go.mod

and in the Dockerfile, pin to the major and let the go line in go.mod pull a newer toolchain if it needs one:

FROM golang:1 AS builder

The action pins have moved too. The posts use actions/setup-go@v5 and golangci/golangci-lint-action@v4. Setup-go is at v7, and the lint action is at v9, which matters more than a bump usually does because v6 of the action was the last to work with golangci-lint v1. The alpine:3.19 runtime image in the same post is also past its end of life, and golang:1-alpine currently means Alpine 3.24.

The golangci-lint config is the old format, and part of it was already invalid

The linting post ships a .golangci.yml with linters-settings, issues.exclude-rules and govet: check-shadowing: true. golangci-lint v2 shipped in March 2025 with a new config shape, and the migration tool told me something I had not noticed: the check-shadowing key was rejected by the v1 schema too. It had been removed in favour of enable: [shadow] before the post went out.

Running golangci-lint migrate --skip-validation over the post's file produces this:

version: "2"
linters:
  enable:
    - gosec
    - misspell
  settings:
    errcheck:
      check-type-assertions: true
    gocyclo:
      min-complexity: 15
  exclusions:
    generated: lax
    presets:
      - comments
      - common-false-positives
      - legacy
      - std-error-handling
    rules:
      - linters:
          - gosec
        path: _test\.go

Five of the eight linters have gone from the enable list because errcheck, govet, ineffassign, staticcheck and unused are the v2 default set, and gosimple is gone because it was merged into staticcheck. The install line changed as well. The module path is now github.com/golangci/golangci-lint/v2/cmd/golangci-lint, and the project's own docs say that go install and the tool directive "aren't guaranteed to work" and recommend the binary install script. The post's @latest install would have quietly stayed on v1 forever.

b.N loops where b.Loop goes

The benchmarks post says "that b.N is key" and writes nine benchmarks around it. Go 1.24 added testing.B.Loop, and the release notes list two reasons to prefer it: the benchmark function runs exactly once per -count, so setup runs once, and "function call parameters and results are kept alive, preventing the compiler from fully optimizing away the loop body."

The second one bit the post's very first example. Here is BenchmarkAdd both ways:

func BenchmarkAddN(b *testing.B) {
    for i := 0; i < b.N; i++ {
        Add(2, 3)
    }
}

func BenchmarkAddLoop(b *testing.B) {
    for b.Loop() {
        Add(2, 3)
    }
}

Benchmark	ns/op	What it measured
`BenchmarkAddN`	0.23	an empty loop
`BenchmarkAddLoop`	1.58	the call

go1.27.2, darwin/arm64, Apple M4 Max, best of three with -count=3.

The b.N version inlines Add, sees the result is unused and deletes it, so the number is the cost of incrementing i. The post presented that as a working benchmark. Go 1.26 also removed the one cost of switching: b.Loop no longer blocks inlining inside the loop body, so there is no reason left to write the old form. The post's b.ResetTimer() calls go too, since Loop resets the timer on its first call.

omitempty has a replacement, and json has a second package

The JSON post has a whole section called "The omitempty Gotcha" and ends it by reaching for pointers so that zero and absent can be told apart. Go 1.24 added omitzero. The release notes describe it as "clearer and less error-prone than omitempty when the intent is to omit zero values" and call out the case that most often hurt: omitempty never omitted a zero time.Time, because a struct is not one of the "empty" kinds, so every optional timestamp serialised as 0001-01-01T00:00:00Z.

type Empty struct {
    When time.Time `json:"when,omitempty"`
}
type Zero struct {
    When time.Time `json:"when,omitzero"`
}
// Empty{} marshals as {"when":"0001-01-01T00:00:00Z"}
// Zero{}  marshals as {}

omitzero calls IsZero() if the type has one and falls back to the zero value otherwise, which is also the hook you want for your own types. The pointer trick still works and still has a job when zero is a meaningful value you want to send. For the common case, the section is now a one-liner.

The other half of this is Go 1.27 switching encoding/json over to the v2 implementation underneath. I checked what that changes for code written against the old API, because the v2 defaults are stricter, and the answer is less than I had expected. The old encoding/json on 1.27 still accepts duplicate object keys (last one wins) and still replaces invalid UTF-8 with U+FFFD, exactly as it did on 1.25. The release notes say so: "Behavior is preserved, though error message text may differ." The strict behaviour lives in the new encoding/json/v2 package, which rejects both:

jsontext: duplicate object member name "a"
jsontext: invalid UTF-8 after offset 1

So the migration risk is in choosing to import v2, not in bumping the toolchain. If you consume JSON from systems you do not control, that is the moment to test. Coming from System.Text.Json, which is strict by default, the v2 behaviour will feel like home.

What did not need correcting

The things I expected to have to walk back held up. Goroutines against async/await, the error handling argument, the single binary deployment story and the escape analysis post all read the same against 1.27 as they did against 1.22. The language has added range-over-func iterators and, this August, generic methods, and the iterators post covers both. Everything else was a version number.

Each of the six posts above now carries a dated note pointing here, and the code in them stays as it was. The series is a record of what Go looked like when I learned it, and the notes are the diff.