DEV Community: Yusuf İhsan Görgel

The Biggest MCP Update Ever, Explained With a Restaurant

Yusuf İhsan Görgel — Wed, 29 Jul 2026 06:43:25 +0000

MCP 2026-07-28 is out, and sessions are gone. The whole thing in plain English.

Before: the balancer is sticky, so every request goes to Instance A and dies with it. After: the next free instance takes it.

There is a restaurant in your city with one very good waiter. He remembers everything. Your table number, your no-onions rule, the fact that your friend wants the bill split in two. You never repeat yourself.

Then the waiter gets sick.

The new waiter knows nothing. Not your order, not the onions, not the split bill. You start again from zero. The whole restaurant, it turns out, was running on one person's memory.

Until this week, the Model Context Protocol worked exactly like that restaurant.

First: what is MCP?

If you have never heard of MCP, the docs' own one-line pitch is the fastest start: a USB-C port for AI applications. It is an open standard. It lets AI applications (Claude, IDEs, chatbots, agents) plug into tools and data the same way, no matter who built them.

Without a shared protocol you build one integration per pair. With one, you build one per side.

In our restaurant: your AI app is the host, and it sends one client to each kitchen it wants to order from. You, at the counter, are that client. The kitchen is the server, a program that offers tools, resources (files and data), and prompts. The dishes on the menu are the tools. And MCP itself is the ordering system: how you ask, how the kitchen answers, what happens when something goes wrong.

On July 28, the MCP team released the 2026-07-28 revision (their word for a version). When the release candidate went out in May they called it the largest revision of the protocol since launch. Having now read the whole diff, I would not argue: it changes the ordering system from top to bottom.

The waiter is gone: MCP is now stateless

In the old protocol, a client and a server first did a handshake called initialize, a "hello, who are you?" step. After that, the server kept a session for you. On HTTP there was even a special header, Mcp-Session-Id, that locked you to one specific server instance (one running copy of the server).

That session was the waiter's memory, and it had the waiter's weakness. If the instance holding it crashed, your session died with it. So if you ran three copies of the server, the load balancer in front of them had to be sticky: it had to send you back to the same copy every time, the way a host sends you back to the same waiter. Serverless platforms broke this outright. Services like AWS Lambda start and stop instances whenever a request arrives, so there is no same copy to go back to.

The new version removes sessions from the protocol completely. initialize is gone. Instead, every request carries everything the server needs, inside a small _meta block: which protocol version you speak and what your client can do. Just the technical facts, not your conversation; anything else the server needs arrives as normal request parameters.

So the restaurant reopened as a counter-service place: you order at the counter, receipt in hand. Your whole order is printed on the receipt, and any cashier can pick it up and serve it. If one cashier goes home, the next one reads the same receipt and continues. Nobody has to remember you.

Stateless does not mean your server has to forget everything. It means the protocol no longer remembers for you. If a server needs state across calls, it mints its own handle and returns it from a tool like any other output. The model passes that handle back as an ordinary argument on the next call, so the state is visible in the request instead of hidden in the transport. It is the ticket number on your receipt: the counter does not know who you are, but it knows what number 47 ordered.

Old: one waiter's memory. New: a receipt any cashier can read.

The smallest possible before and after:

// Before (2025-era): a handshake first, then a session to protect
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "my-app", "version": "1.0.0" }
  }
}

// After (2026-07-28): no handshake, the receipt carries everything
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

The animation at the top of this article is the same story in fifteen seconds. On the left the host is sticky: every request goes to Instance A, with a session tag pinned to it, and when A dies the client dies with it. On the right the host sends each new arrival to whichever counter is free, taking turns between A, B and C. When A dies, the queue keeps moving.

This is the payoff. You can now deploy an MCP server on serverless or edge platforms (small servers close to the user), or scale it behind any ordinary load balancer.

The card at the door: `server/discover`

Without a handshake, how do you learn what a server offers? One new call: server/discover. It returns the server's capabilities (what it can do) and the protocol versions it supports, in a single response, and every 2026-07-28 server must implement it. Clients do not have to call it: you can send tools/list straight away and handle an unsupported-version error if one comes back. server/discover is there for when you want the whole picture up front, and it is how you probe an older server over stdio.

There is now a card at the door listing what this branch can do. You still ask for the dishes separately, with tools/list. The card even says how long it stays fresh.

Capabilities at the door, dishes on the menu. Two different calls.

The buzzer: `subscriptions/listen`

Sometimes the kitchen needs to tell you something: a resource changed, the tool list was updated. The old protocol did this with a stream over HTTP GET (a stream is a connection that stays open so the server can keep sending; over HTTP these are SSE, Server-Sent Events), plus separate resources/subscribe and resources/unsubscribe calls. All of that is replaced by one method: subscriptions/listen.

Think of the buzzer they hand you at the counter: it sits on your table and rings only when your order changes. You tell the server what you care about (a resource changing, or the tool or prompt list changing), and the server opens a stream tagged with your subscription ID. When the server wants to close the stream on purpose, it should now say a proper goodbye: a small "complete" result carrying that same ID. That way your client knows the difference between a normal close and a broken connection.

One buzzer replaces the old GET stream and both subscribe calls.

Something else quietly disappeared: you can no longer resume a broken stream. The old spec let you pick up where you left off with a Last-Event-ID header, which meant the server had to remember what it had already sent you. State again, hiding in the transport. Now, if a stream breaks, you send the request again with a new ID. If your buzzer breaks, nobody repairs it mid-ring; you take a new buzzer from the counter.

The question written on your receipt: MRTR

Nobody can come to your table anymore; the waiter who would have carried the kitchen's question is gone. So the cashier writes on your receipt: "Which sauce?" You come back to the counter with the same receipt and the answer written on it. Any cashier can complete the order from there. That is the pattern the spec settled on, and it has a name: Multi Round-Trip Requests (MRTR).

In the old protocol, a server could send requests back to the client in the middle of an operation. For example: "please ask the user a question" or "please run this through your model". That needs a two-way, stateful channel (stateful means the server must remember you between messages), which is exactly the thing the new version threw out.

The replacement: when a server needs something from you, it does not call you. It finishes the current request with a result marked resultType: "input_required", and lists what it needs in inputRequests. Your client then retries the same request with the answers attached. If the server sent a state token, the client sends that back too, unread; that is the note scribbled on your receipt. The server reads it and picks up where it stopped.

The kitchen writes its question on your receipt. You come back with the answer.

This is also why every result must now declare a resultType, either "complete" or "input_required". If an older server sends nothing, clients treat it as "complete".

The menu photo has an expiry time: caching hints

There is a photo of the menu taped up, with a note on it: valid for 10 minutes. That is what the new caching hints are. Being stateless has a cost, because clients ask "what tools do you have?" far more often, so the spec standardises the answer's shelf life.

Five results (tools/list, prompts/list, resources/list, resources/read, resources/templates/list) plus server/discover now carry two required fields: ttlMs and cacheScope. ttlMs is how long the result stays valid, in milliseconds. cacheScope decides who else may reuse it: "private" means only the same logged-in user (the same auth token), "public" means anyone. The photo either goes on the public board next to the card at the door, or stays on your table where only you can use it. Only final "complete" results carry these hints; an "input_required" half-answer can never be saved for reuse.

The complaint codes on the wall

Every branch of the restaurant now prints the same complaint codes on the wall. Error codes were renumbered and, for the first time, given a real rule about who owns which numbers: header mismatch is -32020, missing required client capability is -32021, unsupported protocol version is -32022. The range -32020 to -32099 now belongs to the spec itself, and servers and clients must not invent their own codes inside it. One older number moved too: resource not found is now -32602 instead of -32002, so clients should keep accepting the old code from older servers. Your client can react to a number instead of reading an error message and guessing.

The old side door is closing

A release this big also says goodbye to things:

Roots, Sampling and Logging are deprecated: still working today, marked for removal. Roots let a server see your folders; Sampling let it borrow your model. Logging control moved into _meta, so you set a logLevel per request instead of calling logging/setLevel.
ping, logging/setLevel, and the roots list-changed notification are removed.
The original HTTP+SSE transport from 2024 (a transport is the way messages travel) is now formally deprecated under the new lifecycle policy.
Tasks moved out of the core into an extension, so the core spec stays smaller.
OAuth Dynamic Client Registration is deprecated and replaced by Client ID Metadata Documents. Skip this bullet if you do not touch OAuth.

The old side door still opens for a while, because the spec defines careful rules for talking to older servers. But the sign on it now says: please use the main entrance.

Why I am the one telling you this

I am not neutral about this release. For the last few weeks I have been moving the Dart team's MCP SDK (package:dart_mcp) to it, with five merged pull requests so far in dart-lang/ai. The work is tracked publicly in dart-lang/ai#162. When the final spec came out, I compared it line by line with the release candidate (the near-final draft) and posted the report there. So everything above comes from the schema and the docs themselves, not from a summary of a summary.

What this means for you

If you build apps that use MCP servers: wait for your SDK to update. After that there is less to get wrong: no handshake, no session to lose. Version and capabilities travel with every request.

If you write MCP servers: tape this one to the kitchen wall. server/discover is mandatory now, and every result needs a resultType. Your */list and resources/read results need ttlMs and cacheScope on top of that. The painful part is anywhere you used to call back into the client: that has to be redesigned around input_required, and it changes your control flow, not just your types. What you get back is a server that runs anywhere.

If you are just curious: the practical news is freedom in where servers can run. MCP servers used to need a machine that stays up and remembers things. Now they can run as short-lived functions close to users, and scale like any normal web service.

Also changed, in one breath

A few smaller items, so you know they exist:

The OpenTelemetry keys traceparent, tracestate and baggage got reserved slots in _meta, so one request can be traced across services.
tools/list should now return tools in a stable order.
A tool parameter can now be mirrored into an HTTP header with the new x-mcp-header annotation, under strict naming rules.
clientInfo is no longer required on requests, and servers should now send serverInfo in every result's _meta. Both are recommended, not mandatory.
JSON Schema $ref resolution over the network (fetching schema pieces from other servers) is now banned by default.

None of it changes the story above. It is the boring kind of change, which in a protocol is the good kind.

Your receipt, please

A restaurant that runs on one waiter's memory is a lovely place, right up until the day he is not there. Counter service is duller. It also never loses your order, and it can open a hundred branches without breaking.

MCP just made that trade-off, and I think it chose well. If you want to see the change happen in real code, the Dart migration in dart-lang/ai#162 is open to read, one pull request at a time.

The object that falls out of the Set it is still in — mutable hashCode in Dart

Yusuf İhsan Görgel — Fri, 24 Jul 2026 08:39:13 +0000

Here is a Set with one element. One assignment later, contains stops finding it:

final attrs = <String, Object?>{'page': 1};
final tag = Tag('intro', attrs);
final seen = {tag};

print(seen.contains(tag)); // true
attrs['page'] = 2;
print(seen.contains(tag)); // false
print(identical(tag, seen.first)); // true

The object is in the set. identical confirms it is the same object. seen.contains(tag) says it isn't there. All I did in between was change a map I had a reference to.

I shipped this aliasing bug three times across two of my own packages before I caught it — once with the map feeding hashCode, exactly the version above — so this is not a contrived puzzle. It is what happens when a value type puts a mutable field into its hashCode.

Why the set loses it

Set is a hash set. When you add an object, it computes hashCode, picks a bucket, and drops the object in. When you later ask contains, it computes hashCode again, goes to that bucket, and looks. If the two hashes differ, it looks in the wrong bucket and finds nothing.

That's fine as long as hashCode never changes while the object is in the set. It is the one rule hashing depends on.

Here is the Tag that breaks it:

class Tag {
  Tag(this.name, this.attrs);
  final String name;
  final Map<String, Object?> attrs; // stored by reference

  @override
  bool operator ==(Object other) =>
      other is Tag && name == other.name && _mapEquals(attrs, other.attrs);

  @override
  int get hashCode => Object.hash(name, _mapHash(attrs));
}

// Element-wise, one level deep: each value compares and hashes with its own
// == and hashCode. package:collection's MapEquality does the same thing.
bool _mapEquals(Map<String, Object?> a, Map<String, Object?> b) {
  if (a.length != b.length) return false;
  for (final k in a.keys) {
    if (!b.containsKey(k) || a[k] != b[k]) return false;
  }
  return true;
}

int _mapHash(Map<String, Object?> m) {
  var h = 0;
  for (final e in m.entries) {
    h ^= Object.hash(e.key, e.value); // xor: order-independent
  }
  return h;
}

attrs is final, so it looks immutable. It isn't. final freezes the reference, not the map it points at. The constructor stored the exact map the caller passed, and the caller still has it. When they write attrs['page'] = 2, they are writing into the same map tag.attrs reads. hashCode folds attrs in, so the moment the map changes, tag's hash changes, and the bucket the set filed it under no longer matches the bucket contains computes. The object is sitting in the set, in a bucket the lookup never visits.

The final is the tell that makes this easy to miss. It reads as a guarantee of immutability, and for an int or a String it is one. For a Map or a List it guarantees only that you won't reassign the field.

Two ways to be correct

The rule is narrow: anything that feeds hashCode must not change while the object could be in a hashed collection. There are two honest ways to satisfy it.

The first is to not put mutable state in equality at all. If Tag is a handle to something — it owns a resource, or it wraps a big buffer you mutate in place — then value equality is the wrong model, and identity equality (the default, no == override) is correct. Two handles are the same when they are the same object, and nothing can drift.

The second, when the type really is a value and callers will compare it, is to make the state actually immutable — copy it in, and hand back something no one can write to:

class Tag {
  Tag(this.name, Map<String, Object?> attrs)
      : attrs = Map<String, Object?>.unmodifiable(attrs);
  final String name;
  final Map<String, Object?> attrs;
  // == and hashCode unchanged
}

The constructor now takes the caller's map as a parameter and stores a separate, unmodifiable copy. The caller can do whatever they like to their map; it's not the one Tag holds. And tag.attrs['page'] = 3 throws instead of silently corrupting the object. Rerun the first snippet against this version and contains stays true.

Map.unmodifiable copies the top level, which is what the hash reads, so that is where it has to be. If you nest a mutable List or Map as a value inside attrs, that inner collection is still shared and still mutable, so either document that equality compares those by identity or freeze them too. Be explicit about which; a half-frozen value type is its own trap.

Where this actually bites

Nobody writes attrs['page'] = 2 right after building a Tag on purpose. It happens at a distance. A store keeps the objects in a Set or uses them as Map keys, hands one back to you, and you update its metadata — reasonable, the field is right there — and now a Set somewhere else silently can't find it. Or a builder reuses one map across several objects, filling it in between, and they all end up sharing state. The failure surfaces far from the mutation, as a lookup that misses or a deduplication that doesn't dedupe, with no error to trace back.

The check is quick. For every type in your public API that overrides ==, ask what its hashCode reads, and whether any of it can change after construction. If it can, either drop value equality or copy the mutable parts in. Add one test that puts an instance in a Set, mutates the collection you handed the constructor, and asserts the instance is still found — the assertion is one line and it fails loudly the day someone reintroduces the reference.

My CI ran on three platforms and still could not catch this

Yusuf İhsan Görgel — Fri, 24 Jul 2026 01:50:11 +0000

For thirteen releases, my Ogg/MP3 decoder's README said this:

it decodes the same bytes to the same samples on every platform

I believed it. The decoding happens in C, the C is compiled from the same source everywhere, the tests pass on macOS, Linux and Windows. Where would a difference even come from?

I was getting the package ready to freeze at 1.0.0, which is the point where a documented promise stops being a sentence and becomes a contract. So instead of reading the claim again, I tested it. It is false, and it has been false since the first release.

Testing a claim about two architectures needs two architectures

That sounds obvious written down. It is exactly what my CI did not do.

On an Apple laptop you can do the whole thing locally, because clang will cross-compile and Rosetta will run the result. The driver ships in the repo at doc/blog/cross-arch/detdrv.c; from a fresh clone, run these at the repo root:

cp doc/blog/cross-arch/detdrv.c .
clang -arch arm64  -O3 -Isrc/third_party -o det_arm64  detdrv.c src/*.c
clang -arch x86_64 -O3 -Isrc/third_party -o det_x86_64 detdrv.c src/*.c

detdrv.c is about fifty lines: read a file, call the package's own decode function, print the channel count, the sample rate, the frame count, and an FNV-1a hash of the decoded samples. Then run both binaries over the six test fixtures and compare the hashes. src/*.c here is the package's two C files, and -O3 is what the build actually uses, so this is the production configuration rather than a special one. The x86-64 binary runs under Rosetta, but Rosetta only executes the instructions it is handed; anything the two binaries disagree on was decided when clang compiled them, not at run time.

Five of the six came back different.

fixture                      arm64             x86_64            same?
sine_44100_mono_1s.mp3       26f26e4d00bd4680  db3ed41489553717  NO
sine_44100_mono_1s.ogg       741546cc3f0e3857  9b9fa075856e40b1  NO
sine_44100_stereo_1s.mp3     62655177b196b90f  db39b9b9973061b7  NO
sine_44100_stereo_1s.ogg     b712d80468229e7f  ab1522a686a648df  NO
sine_48000_mono_halfsec.mp3  03a0cfb92eff3109  03a0cfb92eff3109  yes
sine_48000_mono_halfsec.ogg  0e38543dbad39c7e  db914b5a5a724d93  NO

Same source, same compiler, same optimisation level, same input bytes. Different samples. The one that matched, a short MP3, matched by luck rather than by rule: the divergence only shows up when a sample lands close enough to a rounding boundary to fall the other way, and that clip happened to have none.

How big, exactly

A hash mismatch tells you nothing about severity, so the next step is to dump both PCM buffers and diff them sample by sample:

sine_44100_mono_1s.ogg      12 of 44100 samples differ (0.027%), max delta 1 LSB
sine_44100_mono_1s.mp3       3 of 47232 samples differ (0.006%), max delta 1 LSB
sine_44100_stereo_1s.ogg    16 of 88200 samples differ (0.018%), max delta 1 LSB
sine_44100_stereo_1s.mp3    10 of 94464 samples differ (0.011%), max delta 1 LSB
sine_48000_mono_halfsec.ogg  5 of 24000 samples differ (0.021%), max delta 1 LSB

That is all five of the fixtures that diverged. Every difference is one least-significant bit, on a fraction of a percent of samples. In 16-bit audio one LSB is one part in 32768 of peak amplitude. Nobody is going to hear it. The frame count, channel count and sample rate matched on both architectures for all six fixtures.

So the audio is fine. The sentence is not.

Where the bit goes missing

Both decoders do their arithmetic in floating point, and the C standard lets a compiler contract a multiply followed by an add into a single fused multiply-add. An fma computes a * b + c with one rounding instead of two, so it is more accurate, and it produces a different number than the unfused version.

arm64 has an fmadd instruction and clang uses it freely. Baseline x86-64 does not guarantee FMA, so on that target the same expression compiles to a separate multiply and add, with a rounding in between. One rounding versus two, in a decoder that then scales to 16-bit integers, and occasionally a sample lands on the other side of .5.

This is not a bug in the two decoders this package vendors — stb_vorbis for Ogg and minimp3 for MP3 — nor in clang or my shim. It is the default behaviour of C floating point, and -ffp-contract=off turns it off. I checked what the build actually passes: only an optimisation level, no floating-point flags, so contraction is on, and the divergence I had documented as impossible is exactly what the default asks for.

For stb_vorbis that flag is the whole story. Rebuilt with contraction off, all three Ogg fixtures decode identically on both architectures. But the two MP3 fixtures still differ. I disassembled the contraction-off arm64 build: it contains zero fused multiply-add instructions, so whatever is left cannot be a fused-versus-unfused split.

It is minimp3 hand-writing its final float-to-int16 conversion once per instruction set, and the two versions round differently. The SSE path converts with _mm_cvtps_epi32, which rounds to nearest and breaks ties to even. The NEON path adds 0.5f and truncates. The float values feeding that step are bit-identical on the two architectures once contraction is off — I decoded to float on both and hashed the result to check — so the entire residual difference is those two rounding rules disagreeing, on a handful of samples, by one. Force the plain scalar path with -DMINIMP3_NO_SIMD, which also adds 0.5f and truncates, so x86-64 now rounds the way the NEON path does, and with contraction off as well all six fixtures finally match.

The part worth generalising

My CI matrix is three jobs: macOS (arm64), Ubuntu (x64), Windows (x64). It looks like it covers this. It cannot.

Each job builds the package and runs the test suite, and the test suite checks that decoding produces the right frame count, the right sample rate, and a waveform whose dominant frequency is the tone it should be. Every one of those assertions is a comparison against itself, inside one job. Nothing ever compares the macOS output against the Ubuntu output, because nothing in the matrix has both.

The trap is not specific to audio:

No number of independent self-comparisons tests a cross-environment claim. The only test is to carry an output from one environment into the other and compare — which a matrix that never moves an output between jobs does not do.

The fix in CI, if you need the guarantee, is to have jobs upload a hash of the output and have a final job assert they all match. The fix in the docs, if you do not need the guarantee, is to stop claiming it.

What the docs say now

I took the second option, because bit-identical cross-architecture output is not worth turning off contraction and minimp3's SIMD paths for a decoder whose output goes to a waveform or an FFT:

Decoding is deterministic for a given build: the same bytes decode to the same samples every time, and the geometry (channel count, sample rate, frame count) is the same everywhere. Sample values are not bit-identical across CPU architectures, though. [...] Measured across this package's own fixtures, that is around 0.03% of samples differing by one least-significant bit: inaudible, but enough that a checksum of decoded PCM will not match across a mixed-architecture fleet.

That last clause is the only case where any of this bites. If you decode audio on a build machine and compare a hash against audio decoded on a user's machine, or you cache by content hash across a mixed fleet, you will get misses that look like corruption and are not. Everyone else can ignore the whole thing, which is why the honest version of the sentence is longer than the false one.

If you maintain a native package that computes in floating point, the check costs one afternoon: build for two architectures, hash the output, compare. I would not assume the answer.

The 24.8 milliseconds you pay before ffmpeg decodes a single sample

Yusuf İhsan Görgel — Fri, 24 Jul 2026 01:50:09 +0000

You have an .ogg file and you need the raw samples. In Dart there is no decoder in the standard library, so you do the normal thing: you shell out to ffmpeg, read its stdout, and get your PCM. It works, it is one line, and ffmpeg is better at codecs than anything you are going to write.

I wanted to know what that costs, so I measured it against decoding in the same process. The interesting number turned out not to be the one I went looking for.

The measurement

Four clips of a 440 Hz sine, 44.1 kHz stereo, Vorbis in Ogg, at 1, 5, 15 and 30 seconds. Two ways to turn each one into interleaved 16-bit PCM:

In process. decodeOgg(bytes) from my audio_decode package, which compiles stb_vorbis from source through a Dart build hook and calls it over FFI.
Subprocess. ffmpeg -i clip.ogg -f s16le -acodec pcm_s16le -, run with Process.runSync, reading the PCM off stdout. ffmpeg 8.1.1.

Nine runs each, median reported, Apple M-series laptop. The bench checks that both paths produce the same amount of audio before it trusts either timing, which matters more than it sounds like and which I will come back to.

clip	in process	ffmpeg	ratio
1 s	0.594 ms	25.221 ms	42x
5 s	2.108 ms	27.406 ms	13x
15 s	6.294 ms	32.746 ms	5x
30 s	12.923 ms	40.452 ms	3x

Run to run these move by a few percent, and more than that on the sub-millisecond cell: a second run, from a fresh clone of the repo, gave 0.622 ms and 24.727 ms in the first row. Nothing below depends on the third decimal.

A 42x ratio at one second is the sort of number that ends up in a README, and it would be a dishonest one. Look at what the ffmpeg column actually does: thirty times more audio, and the time goes up by 15 ms. The clip length is barely moving that number. Something else is most of it.

The floor

The way to find out is to give ffmpeg nothing to do. I encoded a 0.05-second clip, 4 KB, and decoded it the same way:

Decoding a 0.05 s clip through ffmpeg still takes 24.793 ms, so that
is roughly what the process itself costs, before any audio is decoded.

That is the answer. About 24.8 ms of the 25.2 ms at one second is not decoding. It is fork, exec, the dynamic linker resolving ffmpeg's dependencies, ffmpeg parsing its arguments, probing the input format, setting up filters, and tearing all of that down again.

Subtract it and the two decoders look like what they are, which is two competent implementations of the same codec:

clip	in process	ffmpeg, decoding only
1 s	0.594 ms	0.428 ms
5 s	2.108 ms	2.613 ms
15 s	6.294 ms	7.953 ms
30 s	12.923 ms	15.659 ms

ffmpeg is faster than me at one second and I am faster at thirty. Nobody should switch decoders over that. The 24.8 ms is the whole story, and it has nothing to do with audio.

What it actually costs you

Because the floor is fixed per invocation, the arithmetic is per file, not per second of audio:

One 30-minute podcast: ffmpeg spends ~25 ms starting up and around a second decoding. The startup is 2-3% of the job. Shell out; it is fine.
A thousand short voice clips: 1000 × 24.8 ms is about 25 seconds, spent entirely on process startup, before counting a single sample. Batch them into one ffmpeg call and that goes away, but the moment the files arrive one at a time, or need different decode options, you are back to paying it per file. In process, it never exists.
A Flutter app decoding a clip in response to a tap: 25 ms is a frame and a half at 60 fps, on top of whatever the decode costs, and you cannot amortise it because there is one clip.

That last one is the case where it stops being an optimisation and becomes a design constraint. It is also the case where shelling out is often not available at all: on iOS you cannot spawn a process, so there the subprocess column is not a slower option, it is not an option.

The honest summary is narrow. If you decode occasionally, or in a batch job where a few seconds of overhead disappears, run ffmpeg and enjoy its enormous format coverage. If you decode many files, or decode on a latency budget, or ship somewhere without a shell, the per-file floor is the reason to pull the decoder in process.

The check that made the numbers mean anything

Before the bench times anything, it decodes the clip both ways and checks that each produced the same amount of audio. This felt like belt-and-braces when I wrote it. It was not.

A first, stricter version of the check compared the raw sample counts and threw:

sample count differs for 1s: 88200 vs 87944

128 frames short, 256 samples across the two stereo channels, on the one-second clip only. Two decoders disagreeing about how much audio is in a file is exactly the kind of thing that quietly makes a benchmark meaningless, so I went and looked instead of loosening the check.

The container settles it. ffprobe reports duration_ts=44100 for that clip, which is the frame count the Ogg stream declares. My decoder returns 44100 frames. ffmpeg's raw PCM pipe delivers 43972, stopping 128 frames early, and only at the shortest clip:

1s:  declared 44100     audio_decode 44100     ffmpeg pipe 43972
5s:  declared 220500    audio_decode 220500    ffmpeg pipe 220500
15s: declared 661500    audio_decode 661500    ffmpeg pipe 661500
30s: declared 1323000   audio_decode 1323000   ffmpeg pipe 1323000

A tail-trimming edge case at very short durations. 128 frames is 2.9 ms of audio, so for most uses it does not matter. But it does mean the check has to be about how much audio each side produced, counted in frames, not about the samples matching byte for byte. The samples do not match byte for byte, and that is the second thing worth knowing: stb_vorbis and ffmpeg's Vorbis decoder are two different decoders, so about half the samples differ by one least-significant bit. Both are correct; floating-point Vorbis synthesis simply does not have a single right answer to the last bit. A check that demanded identical samples would fail on every clip and tell you nothing.

So the check counts frames: it reports the 128-frame gap rather than hiding it, and fails only if the two decoders ever disagree by more than about a thousand frames, a codec block's worth, which would mean one of them is genuinely dropping audio. A benchmark that does not check that both sides did the same work is measuring something, and you do not know what.

Run it yourself

The timings in this post come from a script in the package, not from my notes:

git clone https://github.com/Yusufihsangorgel/audio_decode
cd audio_decode
dart run bench/vs_ffmpeg.dart

It needs ffmpeg on your PATH and a C toolchain for the build hook, generates its own clips, and prints the table above plus the measured floor for your machine. If your floor is very different from 24.8 ms I would genuinely like to know: process startup varies a lot by OS and by how ffmpeg was built, and the whole argument in this post is downstream of that one number.

None of this is specific to audio. Shell out to a tool in a hot path and you pay for the process, not the tool, at the same price whether you asked it to do a little work or a lot.

Pinning the point you pinch: the one line behind anchored zoom

Yusuf İhsan Görgel — Thu, 23 Jul 2026 20:41:57 +0000

Open a photo on your phone and pinch to zoom. The spot between your fingers stays between your fingers while everything around it grows. Trackpad pinch, scroll-wheel zoom on a map, double-tap to zoom into a diagram: same feel. Whatever point you aim at holds still while the view scales around it.

That behavior is anchored zoom, and it comes down to one line of arithmetic. This post is about that line. The example package is photo_zoom, which I maintain, but the math is the same whether you are building an image viewer, a map, a canvas, or a diagram editor.

That is a conceptual illustration of the behavior. It is not a screen recording of the Flutter widget. The marked point holds its spot on screen while the grid scales, then the whole view pans.

A view is a scale and a translation

A zoomable view maps content coordinates (where a pixel sits inside the image or the map) to screen coordinates (where it lands on the display). In one dimension the entire mapping is one equation:

screen = scale * content + translation

scale is how far you are zoomed in. translation is how far the content is shifted. Two numbers per axis, and that is the whole transform.

Now zoom in, meaning raise scale, and leave translation alone. Every content value gets multiplied by a bigger number, so every point moves, including the one you were looking at. The image balloons toward a corner and the thing you cared about slides away.

Pin one point and solve for the rest

Pick the point you want to hold still. Say it sits at content coordinate F, and you want it to stay at screen coordinate S. Put those into the mapping:

S = scale * F + translation

You know S, F, and the new scale. The only unknown is translation, so solve for it:

translation = S - scale * F

That is the line. Recompute it every time scale changes, and the point at F lands on S on every frame. The translation is forced here: once the focal point and the scale are fixed, there is exactly one translation that keeps the point pinned. You never choose it directly.

Where the focal point comes from

A pinch hands you two things: a focal point, which is the midpoint between your two fingers, and a change in scale. Feed that focal point into translation = S - scale * F and the image grows out from between your fingers instead of drifting toward a corner.

The same formula covers the other zoom gestures you already use:

Double-tap to zoom: the focal point is where you tapped.
Scroll-wheel or trackpad zoom on desktop: the focal point is the cursor.

Different input, same math. Whatever point you name as the focal point is the point that stays put.

Two axes, no new ideas

Screens are 2D, and the rule runs on each axis on its own. Same formula, twice:

translationX = focalScreenX - scale * focalContentX

translationY = focalScreenY - scale * focalContentY

There is no cross-talk between X and Y. The point you pinch is pinned horizontally and vertically by the same subtraction.

The line, as code

Here it is as a pure-Dart function. It takes the focal point in both coordinate spaces plus the scale, and returns the translation that pins it, as a record with x and y:

// Given where the focal point is on screen and in the content, and the
// scale, return the translation that keeps the focal point pinned.
({double x, double y}) anchoredTranslation({
  required double focalScreenX,
  required double focalScreenY,
  required double focalContentX,
  required double focalContentY,
  required double scale,
}) => (
      x: focalScreenX - focalContentX * scale,
      y: focalScreenY - focalContentY * scale,
    );

Read the body and it is the 2D formula from the last section. focalScreenX - focalContentX * scale is S - scale * F on the X axis, and the same on Y.

Checking it holds

Here is the check I ran. Drop this into the same file as the function above and run it. It fixes a focal point, zooms from scale 1.0 to 3.0, and pushes the pinned point back through screen = scale * content + translation to confirm it lands in the same place:

void main() {
  const focalScreenX = 200.0;
  const focalScreenY = 150.0;
  const focalContentX = 300.0;
  const focalContentY = 400.0;

  for (final scale in [1.0, 3.0]) {
    final t = anchoredTranslation(
      focalScreenX: focalScreenX,
      focalScreenY: focalScreenY,
      focalContentX: focalContentX,
      focalContentY: focalContentY,
      scale: scale,
    );
    final backX = scale * focalContentX + t.x;
    final backY = scale * focalContentY + t.y;
    print('scale $scale -> translation (${t.x}, ${t.y}); '
        'focal maps back to ($backX, $backY)');
  }
}

Run it and you get two lines. At scale 1.0 the translation is (-100.0, -250.0). At scale 3.0 it is (-700.0, -1050.0). The translation moves a long way between the two, because at 3x the content has to shift much further to hold that one point in place. But the pinned point maps back to (200.0, 150.0) at both scales. That equality, the same screen position at every scale, is the property the formula guarantees.

Where this lives in Flutter

In Flutter the transform is a Matrix4. A Transform widget applies one, and InteractiveViewer maintains one for you as you pan and zoom. The scale and translation from above are entries in that matrix. When you pinch inside an InteractiveViewer, it is running this same focal-point arithmetic to pick the matrix for the next frame.

photo_zoom, the package I maintain, is a drop-in replacement for photo_view that wires this up for image viewing. It reads the pinch, double-tap, and drag gestures, builds the anchored transform internally, and scales the image around the gesture's focal point. A caller uses PhotoView with an imageProvider and, if they want, minScale, maxScale, and initialScale (typed as PhotoViewScale). The anchored-zoom math stays inside; the caller gets zoom that holds where they pinched.

To be plain about what that buys you: anchored zoom is standard behavior. photo_view does it, InteractiveViewer does it, your phone's photo app does it. None of it is special to photo_zoom. The part worth carrying to other projects is the one line, translation = S - scale * F. Once you have seen it you can add anchored zoom to a custom canvas, a diagram editor, or a map yourself.

A wrinkle: when a drag should pan and when it should dismiss

Once you allow zooming, a drag has two possible jobs. It can pan the zoomed image, or it can dismiss the viewer and close the full-screen view. You have to decide which one a given drag means.

The rule that feels right keys off whether there is anything to pan into. While the image is larger than the viewport, there is off-screen content to pan into, so a drag pans. When the image is at or below the fit scale, there is nothing to pan, so a drag can dismiss.

photo_zoom 0.2.1 fixed a case here: dismiss had gone dead once the image was zoomed out below its initial scale. At that point there is nothing left to pan, so a drag should have been free to dismiss, and it was not. This is the kind of edge that shows up only once anchored zoom already works and you start spending time in the zoomed-out state.

Keep this one line

If you keep one thing from this, keep translation = S - scale * F. Recompute it whenever the scale changes, using the focal point the gesture hands you, and the point under your finger stays under your finger. The matrix, the widget, and the package are all wrappers around that subtraction.

A public const constructor is the back door around your factory's validation

Yusuf İhsan Görgel — Thu, 23 Jul 2026 20:15:24 +0000

You put your validation in a factory. Schema.string(pattern: ...) checks that the pattern is a real regex before it hands you an object. Schema.enumeration(values) refuses an empty list and copies the one you pass in. The factory is the front door, and it has a bouncer.

Then someone calls the constructor instead.

If the concrete class has a public constructor sitting next to that factory, it is a second door into the same object, and that door has no bouncer. Everything the factory checked, the constructor skips. This is a general Dart trap, and I hit it in my own package, instructor_dart. The interesting part is why the obvious fix does not work: the constructor is const, and const is exactly what stops it from defending itself.

The setup

instructor_dart takes a plain-Dart schema and a prompt and returns a validated, correctly-typed Dart object from an LLM (OpenAI, Anthropic, Gemini). You describe the shape you want with a small schema API:

import 'package:instructor_dart/instructor_dart.dart';

final email = Schema.string(pattern: r'^[^@]+@[^@]+$');
final priority = Schema.enumeration(['low', 'medium', 'high']);

Schema is a sealed base type with static factory methods: Schema.string(), Schema.integer(), Schema.number(), Schema.boolean(), Schema.enumeration(), Schema.list(), and Schema.object(). Each one returns a concrete type: StringSchema, IntegerSchema, EnumSchema, and so on.

Those concrete types are where the problem lived.

Two doors, one object

Before 0.4.0, the concrete classes had public const constructors. So you could build a StringSchema two ways:

Schema.string(pattern: '(') goes through the factory, which validates.
StringSchema(pattern: '(') goes straight to the constructor, which does not.

Both gave you a StringSchema. Only one of them checked anything. Two of the factory invariants were real, and both were skippable through the raw constructor.

The regex is validated eagerly. Schema.string(pattern: ...) runs RegExp(pattern) at construction time. If you pass a broken pattern, you get a FormatException right there, at the line where you wrote the mistake:

// Schema.string runs RegExp(pattern) and throws FormatException on a bad pattern:
final bad = Schema.string(pattern: '(');

Call the raw StringSchema(pattern: '(') constructor and that check never runs. The broken pattern gets stored and sits there until something tries to match against it, which is usually far away from the typo, in a stack trace that points at the matcher instead of at you.

The enum set cannot be empty, and it gets copied. Schema.enumeration(values) throws ArgumentError if values is empty, and it copies the list with List.unmodifiable. So the allowed set is never empty, and nobody can mutate it after the fact:

final priority = Schema.enumeration(['low', 'medium', 'high']);

The raw EnumSchema(const []) constructor skipped both. You could build an enum that matches nothing, or pass in a list you keep a reference to and change later, out from under the schema.

"Just make the constructor validate itself"

This is the obvious idea, and in Dart it does not work, because these constructors are const.

A const constructor is restricted. It can assign to fields and it can run assert statements in its initializer list. That is the whole menu:

class Port {
  final int value;
  // A const constructor may assert. That is as far as it goes.
  const Port(this.value) : assert(value >= 1 && value <= 65535);
}

assert has two problems for real validation. It only runs in debug mode, so in a release build it is gone. And it takes a boolean condition, so it cannot express "parse this string as a regular expression and throw a FormatException if it fails." There is no way to call RegExp(pattern) from inside a const constructor, and no way to throw an ArgumentError conditionally the way an ordinary method can.

So the real checks have to live somewhere that can run real code: a factory, or a static method. That is the actual reason these packages reach for factories in the first place. The factory is the only place a check can live, and a public const constructor sits right beside it as a way around it.

The fix in 0.4.0

Make the concrete constructor library-private. Each concrete class now has a private named constructor, and the factory routes through it. In shape:

StringSchema has const StringSchema._(...).
Schema.string(...) does its regex check, then calls StringSchema._(...).

From a caller's side, the change is small and total. The factory still works exactly as before:

// Still the way to do it:
final email = Schema.string(pattern: r'^[^@]+@[^@]+$');

Writing StringSchema(pattern: r'^[^@]+@[^@]+$') is now an analyzer error: the class has no accessible unnamed constructor. There is no second door to walk through.

The concrete classes stay exported as types, and that part matters. You still get StringSchema and EnumSchema as return types, you can still switch over the sealed Schema hierarchy and match on them, and you can still read their fields. Closing the constructor closes construction only; the type is still yours to use.

One more thing fell out of this. The factories do not take an isOptional argument, so once the raw constructors were closed, the only way left to mark a field optional is the .optional() method that was the intended one. Removing the public constructor removed the shortcut around that too.

Honest scope: this was mostly preventive

I want to be exact about what this changed, because it did not fix five broken validators.

Of the seven factories, only two enforced an invariant that the raw constructor skipped: string with its regex check, and enumeration with its non-empty-and-copy rule. Those two were real holes, and closing the constructor closed them.

The other five (integer, number, boolean, list, object) forwarded their arguments and validated nothing. For those, there was no bug to fix. Closing their constructors is preventive: it means that the day someone adds a check to Schema.integer(), there is no public IntegerSchema(...) sitting next to it to route around the check. The single construction path is set up before it carries anything worth protecting.

So the count is small: two real checks locked, and five constructors closed before they ever guard anything, with all seven now built through one path.

Why this had to happen before 1.0.0

Removing a public constructor is a breaking change. Any code that wrote StringSchema(...) stops compiling.

Once a package puts out a stable 1.0.0, you cannot take a public constructor away without going to 2.0.0. instructor_dart is young, so the cost of the break right now rounds to zero. After 1.0.0 the same cleanup costs a major version and a migration for everyone who depends on you. This was the cheap moment, so I took it.

If a factory validates, close the constructor

The specific bug was mine, but the shape is everywhere: any value type with a validating factory and a public constructor has a back door. If you write these in Dart, the mechanics are worth keeping in your head. Here is the Port from earlier with the door closed:

class Port {
  final int value;

  // The only real constructor, and it is private.
  const Port._(this.value);

  // The public door, and it can run whatever checks it wants.
  factory Port(int value) {
    if (value < 1 || value > 65535) {
      throw ArgumentError.value(value, 'value', 'must be 1..65535');
    }
    return Port._(value);
  }
}

Give the class a private named constructor (ClassName._), route the factory through it, and if the type is part of a sealed hierarchy, keep the class exported so it still works as a type in returns and switch arms. The const constructor cannot carry the validation itself, because const constructors can only assign and assert. The factory is where the checks live, and a public constructor next to it is a way around them.

Go look at your own value types. If the validation is in the factory and the constructor is public, you have two doors, and callers will find the one without the bouncer.

2.75 seconds or 2 microseconds: the same regex, two engines

Yusuf İhsan Görgel — Thu, 23 Jul 2026 19:59:12 +0000

Here is a regular expression: (a+)+$. Here is an input: a string of 28 a characters followed by one !, which the pattern cannot match.

Ask Dart's built-in RegExp whether the pattern matches that input, and on my laptop it takes 2.75 seconds to return false. Ask Google's RE2 engine the same question about the same bytes, and it returns false in about 2 microseconds. Same pattern, same string, same answer. The only thing that changed is which engine did the matching, and it made the answer arrive roughly a million times sooner.

Both numbers are real. I ran the benchmark on Apple Silicon with Dart 3.11, and both engines saw byte-for-byte identical input. The gap is not something you can close by writing a cleverer pattern. Here is where it comes from, and when it is worth paying RE2's cost to avoid it.

The measurement

The pattern is (a+)+$. The input is n copies of the letter a followed by one !, so the match always fails (the string does not end the way the pattern demands). I fed the identical pattern and input to both engines and timed the match. Times are in microseconds; I write us for microseconds and ms for milliseconds.

n	Dart RegExp (us)	re2 (us)
16	4,712	2 to 3
18	10,490	2 to 3
20	15,671	2 to 3
22	49,416	2 to 3
24	169,381	2 to 3
26	679,067	2 to 3
28	2,746,957 (2.75 s)	2 to 3

re2 sits flat at 2 to 3 us the whole way down the column. Dart's RegExp roughly quadruples every time n goes up by two. By n=28 it is spending 2.75 seconds to answer a yes/no question about a 29-character string.

This is the shape of a ReDoS (regular expression denial of service) bug. A pattern that looks ordinary meets an input that is a little bit adversarial, and one match call ties up the isolate for seconds. This is not hypothetical: in dart-lang/sdk#61284 an ordinary URL pattern froze a running app on iOS. Nobody wrote that pattern to be malicious. It just had the wrong shape and met the wrong input.

Why one explodes and the other does not

Both engines answer the same question. They go about it in completely different ways, and that difference is the entire 2.75-seconds-versus-2-microseconds gap.

A backtracking engine treats matching as a search

For (a+)+ to match a run of a's, the engine has to decide how to divide that run between the inner a+ and the outer repetition. Five a's could be one group of five, or four then one, or two then three, and so on. As long as more a's keep coming, the greedy path just extends and the division never has to be reconsidered; the engine takes the first split that works and moves on.

The trouble starts at the character after the run. In our input that character is !, and the pattern still needs $ (end of string) there. The match fails at that point. A backtracking engine does not give up there. It backs up and tries the next way of dividing the a's, then the next, then the next, on the theory that some other division might let the rest of the pattern match.

The number of ways to split a run of n a's into ordered groups is 2 to the power n-1. At n=28 that is 2^27, which is 134,217,728 divisions the engine works through before it can be sure there is no match. Every extra a doubles that count. That is where the "quadruple every time n goes up by two" in the table comes from: one more character, twice the work; two more, four times.

RE2 does not search

RE2 compiles the pattern once into a finite-state machine. Then it reads the input one character at a time, and instead of tracking a single guess it tracks the entire set of states the machine could be in at that point. Each character advances that whole set by one step. The read pointer only ever moves forward; it never backs up to retry a division, because RE2 is not trying divisions at all. It is asking, after these characters, is any accepting state reachable.

The linear-time guarantee is exactly this: n characters take exactly n steps, and no input, however it is crafted, can push an RE2 match into exponential time. There are no divisions to enumerate, so there is nothing to enumerate exponentially many of.

The engine behind the re2 package is an FFI binding to Google's RE2, the same C++ engine, exposed to Dart.

Why Dart's built-in RegExp is the backtracking kind

Dart's RegExp is Irregexp, the engine that came from V8. Irregexp is a backtracking engine, which is why it is fast and full-featured on ordinary patterns and can handle features like backreferences. The same design is what lets a nested quantifier like (a+)+ blow up. Every backtracking engine behaves this way when a nested quantifier fails to match. The exponential search is the algorithm working as designed. There is no patch for it; a backtracking engine does this by construction.

The million-character match

Because RE2 takes one step per character, you can throw genuinely large input at it and watch the time stay reasonable. Each of these is n a's followed by one non-matching character, the same failing shape as before, just longer:

input length (n)	re2 match time
1,000	50 us
10,000	138 us
100,000	111 us
1,000,000	1,894 us (1.9 ms)

Those numbers do not climb smoothly. At the microsecond scale, fixed overhead (crossing into native code, marshalling the string) and ordinary measurement noise dominate, so n=100,000 can clock in under n=10,000. The trend is the point: ten times the input is nowhere near ten times the time, and a million characters match in 1.9 ms.

Put that same million-character hostile input in front of a backtracking engine on (a+)+$ and it would have 2^999999 divisions to work through, which is longer than the age of the universe. RE2 finishes it in under two milliseconds because it never asks that question.

Using it in Dart

The API is small. You construct a Re2 from a pattern and call hasMatch, firstMatch, or allMatches.

import 'package:re2/re2.dart';

void main() {
  // The classic catastrophic-backtracking pattern.
  final re = Re2(r'(a+)+$');
  final hostile = 'a' * 30 + '!';
  print(re.hasMatch(hostile)); // returns false in microseconds; the built-in
                               // RegExp would take seconds on the same input
  re.dispose();
}

I used 30 a's here; since each a doubles the backtracking engine's work, 30 is well past the point where the built-in RegExp stalls for seconds, while RE2 does not notice the difference.

Re2 implements Dart's Pattern, so an instance drops into String.split, String.replaceAll, and the other methods that take a Pattern. Call dispose when you are done with it; it holds a native resource behind the FFI boundary.

The honest trade-off

RE2 is not a general speed boost for everyday regexes. On ordinary patterns and ordinary input, Dart's built-in RegExp is usually the faster of the two, because every RE2 call has to cross the FFI boundary and marshal the string, and that costs something (roughly 2x in my measurements). What RE2 buys you is a ceiling on match time that holds no matter what the input is. That is a security property, and it only matters when the pattern or the input is outside your control. Most of your regexes run against strings you control, and the built-in RegExp is the right tool for those.

So the rule I use:

Reach for re2 when the pattern or the input is attacker-reachable: user-supplied search terms, validating uploaded content, a WAF-style ruleset, anything where someone else picks the string you match against.
Keep the built-in RegExp everywhere else, which is most places.

One constraint is worth knowing before you commit. RE2 does not support backreferences (\1) or lookaround ((?=...), (?<=...)) at all. Those are the features that force a backtracking implementation and open the door to the exponential blow-up, so RE2 leaves them out by design. A pattern using them throws a FormatException the moment you construct the Re2, long before it could bite you in production.

The 2.75-seconds-versus-2-microseconds gap comes from RE2 refusing to enumerate divisions at all, which is a game a backtracking engine has no way to refuse. Once a regex runs against input someone else chose, the exponential case turns from a curiosity into an availability bug, and a linear-time engine earns its FFI cost. The package is re2 on pub.dev; the engine underneath is the one Google wrote for exactly this problem.

Disclosure: re2 is my package; the RE2 engine it binds is Google's.

A finite loop in skeleton_shimmer that stopped resuming when the loop count was raised

Yusuf İhsan Görgel — Thu, 23 Jul 2026 18:10:24 +0000

The clip above is a conceptual illustration of the behavior, with a card frozen after a finite loop on the left and a card still sweeping on the right. It is not a screen recording of the running widget.

skeleton_shimmer draws a shimmer loading effect, a light gradient that sweeps across gray skeleton placeholders while data loads. It is API-compatible with the shimmer package. Its Shimmer widget takes a loop parameter: loop: 0 sweeps forever, and loop: N stops after N sweeps.

Version 0.2.1 had a bug in the loop: N path. Once a finite loop finished, raising loop at runtime did not start the sweep again. The widget stayed frozen on a static gray field. Version 0.2.2 fixes it with a one-line change, and the reason that line works comes down to how AnimationController behaves when it is parked at one of its bounds.

The symptom

Give the widget loop: 2 and let both sweeps play. The shimmer settles on gray, which is what loop: 2 asks for. Now raise the count to loop: 4 while the widget is on screen. Before 0.2.2, nothing happened. The placeholder stayed gray and static, and the two extra sweeps never ran.

Root cause

The sweep is driven by an AnimationController that animates from its lower bound to its upper bound, 0.0 to 1.0. One pass from 0.0 to 1.0 is one sweep.

A status listener, _onStatus, counts completed passes. Each time the controller reaches the end it increments a completed-loops counter, _completedLoops. While that counter is below the target it calls forward(from: 0) to run the next sweep. Once the counter reaches the target it stops calling forward(from: 0), and the controller is left parked at the upper bound: value is 1.0, its status is completed, and it is not animating. For loop: N that is correct, since the animation is meant to stop after N sweeps.

Raising loop at runtime goes through didUpdateWidget. That resets the completed-loops counter back to 0 and calls a resync method, _syncAnimation, to line the animation up with the new configuration.

_syncAnimation saw that the controller was not animating and tried to resume it with a bare forward(). That is where it went wrong. forward() animates toward the upper bound, and the controller was already sitting at the upper bound with value at 1.0. The remaining distance was zero, so the call was a zero-duration no-op: it scheduled no ticker and did not fire the status listener again. The sweep never restarted, and the widget stayed frozen.

The framework behavior underneath it

This is deterministic, and you can confirm it away from the package with a plain AnimationController. Calling forward() when value is already 1.0 does nothing: the status stays completed and isAnimating stays false. It is a genuine no-op. Calling forward(from: 0) instead sets value to 0.0 and isAnimating to true, and the controller runs again.

The fix

The change is one line in _syncAnimation. The branch before 0.2.2:

  } else if (!_controller.isAnimating) {
    _controller.forward();
  }

And after:

  } else if (!_controller.isAnimating) {
    // A finished finite loop parks the controller at the upper bound, where
    // forward() would be a no-op; restart from 0 so a raised loop count
    // sweeps again. Otherwise (e.g. re-enabled mid-sweep) resume in place.
    _controller.forward(from: _controller.isCompleted ? 0 : _controller.value);
  }

The ternary picks a starting point based on where the controller is parked.

When the controller is completed, meaning it is parked at the upper bound after a finished finite loop, forward(from: 0) restarts it from the beginning. That is the case the old code got wrong, and it matches what the status listener already does between loops.

When the controller is not completed, for example it was stopped mid-sweep because the widget was disabled and is now being re-enabled, forward(from: _controller.value) starts from the value the controller already holds. Setting the start to the current value is a no-op assignment, and the controller forwards from there. For that path the behavior is identical to the old bare forward(). Only the completed case changed.

Two behaviors that had to keep working

First, toggling the widget's enabled flag off and back on in the middle of a sweep resumes in place rather than jumping to the start. A controller stopped mid-sweep is not completed, so the fix sends it down the resume-in-place branch, forward(from: _controller.value).

Second, reduced motion still holds. When the platform's disableAnimations accessibility setting is on, the shimmer freezes on its base color. That path calls _controller.stop(), and the fix does not touch it.

The regression test

A regression test shipped with the fix for exactly this scenario. It mounts the widget with loop: 2 and pumps until the animation settles. Once the finite loop is done the controller stops, so the transient callback count, the number of one-shot callbacks registered for the next frame, falls back to 0. The test then rebuilds with loop: 4 and checks that the sweep resumes, which shows up as the transient callback count going above 0 again.

On the pre-fix code the count stays at 0, because the frozen controller schedules no ticker. After the fix it goes back above 0. I confirmed this by reverting only the fix and rerunning: the test fails before and passes after.

An AnimationController parked at a bound is a quiet trap

Calling forward() toward the bound you are already at is a no-op, and so is reverse() toward the bound you are already at, because the remaining distance is zero. When you want the controller to run again from that bound, you have to say so: forward(from: 0) from the upper bound, or reverse(from: 1) from the lower bound.

The other half of this bug sits in didUpdateWidget. When a runtime parameter change resets internal state, here the completed-loops counter, it has to re-establish the animation to match the new state. Resuming a controller and restarting it are different operations, and the code has to choose the right one for where the controller is parked at that moment.

A route could write index.html outside the output directory: a path traversal fix in flutter_prerender 0.3.2

Yusuf İhsan Görgel — Thu, 23 Jul 2026 17:52:10 +0000

flutter_prerender is a small CLI I maintain on pub.dev. Point it at a flutter build web output and it loads each route in headless Chrome, reads the text out of Flutter's accessibility tree, and writes one static HTML document per route, so crawlers that do not run JavaScript get real content instead of an empty page. Each route is written to <out>/<route>/index.html.

Version 0.3.2, published today, fixes a bug in the step that turns a route into that path. A crafted route could make the writer create index.html outside the output directory, in one case at an absolute path with the output directory dropped entirely. That is an arbitrary file write. It was reachable from a plain routes file or a YAML config, not only from --crawl, and it had been present since 0.1.0.

From a route to a file path

Every route, wherever it comes from, goes through one function, normalizeRoute, and then the writer. The writer does, in effect:

strip the leading slash from the route to get a relative path,
join it onto the output directory with path.join,
create that directory,
write index.html into it.

Routes come from three places: a routes file, a YAML config, or same-origin links discovered with --crawl. All three pass through normalizeRoute and then the writer, so anything normalizeRoute fails to catch reaches the write step.

Before 0.3.2, normalizeRoute only made sure a route began with a leading slash. It prepended one when a route did not have it, and otherwise left the route alone.

Where the routes escaped

A .. segment. Passing ../secret, normalizeRoute prepended a slash and returned /../secret. The writer stripped the leading slash back to ../secret, and path.join(outDir, '../secret') climbs one directory above outDir, so index.html is written outside the directory you chose.

A leading //. Passing //etc/passwd, the route already began with a slash, so normalizeRoute returned it unchanged. The writer stripped one leading slash, leaving /etc/passwd, which is an absolute path. path.join(outDir, '/etc/passwd') returns /etc/passwd: path.join discards everything before an absolute segment, so outDir is dropped and the write lands at an absolute location.

Why a leading-slash check let them through

A leading-slash check looks at the front of the string. /../secret starts with exactly one slash and passes. //etc/passwd starts with a slash and passes. Neither the interior .. nor the second leading slash is something a leading-slash rule examines. Both problems live past the first character.

The fix in 0.3.2

Three parts: reject the dangerous shapes for explicit routes, skip them for crawled links, and check containment at the write boundary.

1. Reject the dangerous shapes in normalizeRoute

For routes the user wrote down, in a routes file or a YAML config, a bad shape is a mistake to fix, so normalizeRoute now throws ConfigException. This code runs at the end of the function, after the leading slash has been normalized into a local route:

  // A route is written to disk as a path under the output directory, so it
  // must not be able to climb out of it. A .. segment would write above the
  // output directory; a leading // is an absolute path that path.join would
  // honour, discarding the output directory entirely.
  if (route.startsWith('//')) {
    throw ConfigException('Route must not start with "//": "$value"$where');
  }
  if (route.split('/').contains('..')) {
    throw ConfigException('Route must not contain a ".." segment: "$value"$where');
  }
  return route;

The message quotes the route and adds the source location when it came from a numbered line in a file.

2. Skip a bad crawled link instead of aborting the crawl

Discovered links are different. One page on the site linking to an odd href should not stop the whole crawl, so the crawl path, sameOriginRoute, catches the ConfigException and skips that link, the same as it skips any other link it cannot turn into a route. It returns null for a link it will not follow.

A crawled link reaches normalizeRoute after one extra step. It is parsed with Uri first, and Uri applies RFC 3986 dot-segment removal. An absolute link like /../secret is collapsed by Uri to /secret before normalizeRoute ever sees it, because .. cannot climb above the root of an absolute path. Only a relative traversal like ../secret keeps its .., reaches normalizeRoute, throws, and gets skipped.

3. A containment check at the write boundary

The last part does not rely on the route being well formed. Before writing, the writer resolves the full target path and refuses to write unless the target is the output directory or inside it. Here p is package:path/path.dart:

  final target = p.normalize(p.join(outDir, relative));
  if (target != outDir && !p.isWithin(outDir, target)) {
    throw ConfigException(
      'Refusing to write route "$route" outside the output directory.',
    );
  }

p.normalize resolves any .. in the joined path first, so the comparison is on the real location, and p.isWithin(outDir, target) is the containment test. This is defense in depth: even if some future route source skipped normalizeRoute, nothing gets written outside --out.

What the functions do now

Both are exported from package:flutter_prerender/flutter_prerender.dart. normalizeRoute(String raw, {int? lineNumber}) returns the normalized route or throws ConfigException. sameOriginRoute(String href, {String? origin}) returns a route string, or null for a link it will not follow. ConfigException is an Exception with a String message.

The behavior on 0.3.2, as a test:

import 'package:flutter_prerender/flutter_prerender.dart';
import 'package:test/test.dart';

void main() {
  test('explicit routes are validated', () {
    expect(normalizeRoute('/about'), '/about');
    expect(() => normalizeRoute('../secret'), throwsA(isA<ConfigException>()));
    expect(() => normalizeRoute('//etc/passwd'), throwsA(isA<ConfigException>()));
  });

  test('crawled links are filtered', () {
    expect(sameOriginRoute('../secret'), isNull);   // relative traversal, skipped
    expect(sameOriginRoute('/../secret'), '/secret'); // absolute, Uri collapses the ..
    expect(sameOriginRoute('about'), '/about');
  });
}

What still works: safe absolute links

The fix targets two specific shapes, so ordinary routes are unaffected, including a safe absolute link that happens to contain ... A link like /../about is absolute, so Uri collapses it to /about before normalizeRoute sees it, the same rule that turns /../secret into /secret. Since .. cannot climb above the root of an absolute path, the link stays a normal in-site route. What gets rejected is a relative ../secret and a literal leading //.

When external input becomes a path

Turning external input into a filesystem path has two traps a leading-slash check does not catch.

A .. segment climbs out of the directory you meant to confine writes to. And path.join(base, x) does not always return something under base: if x is absolute, join returns x and base is gone.

The fix is two layers that do not depend on each other. Validate the logical route by rejecting .. segments and a leading //, then check containment at the write boundary with p.isWithin, so the write cannot land outside the directory no matter how the path was assembled. This is the same shape as classic web path traversal, here in a Dart CLI that writes files.

flutter_prerender 0.3.2 is on pub.dev.

A resolved top-level null was dropped from streamPartialJson (stream_struct 0.3.2)

Yusuf İhsan Görgel — Thu, 23 Jul 2026 17:16:02 +0000

stream_struct takes a stream of text deltas from a model and turns it into a stream of parsed JSON values. The entry point is streamPartialJson:

Stream<Object?> streamPartialJson(Stream<String> deltas)

It accumulates the deltas into a buffer and, after each one, tries to parse the buffer so far. When the buffer parses, it emits the value. It skips deltas that leave the buffer unparseable (a half-written token or object) or whose parsed value matches the last one emitted. A listener sees the object grow as the deltas arrive.

That much worked. The bug was in how the loop decided a delta had produced a value.

The bug

streamPartialJson was built on the exported helper parsePartialJson:

Object? parsePartialJson(String buffer)

parsePartialJson returns Object?, and it returns null in two different situations:

Nothing is decodable yet. The buffer is a partial token like "nu", or a half-written object.
The buffer decoded to the JSON literal null, which is a real, resolved value.

The old streaming loop collapsed both into one check:

final value = parsePartialJson(buffer.toString());
if (value == null) continue;

So a resolved top-level null hit the same branch as "not ready yet" and was skipped. If the whole answer was null, the stream completed having emitted nothing.

Reproducing it

Here is a model that streams the JSON literal null across two deltas:

import 'package:stream_struct/stream_struct.dart';

Future<void> main() async {
  // A model that streams the JSON literal null across two deltas.
  Stream<String> deltas() async* {
    yield 'nu';
    yield 'll';
  }

  final frames = <Object?>[];
  await for (final value in streamPartialJson(deltas())) {
    frames.add(value);
  }
  print(frames);
  // stream_struct 0.3.1: []      the resolved null was dropped, no frame emitted.
  // stream_struct 0.3.2: [null]  the null is emitted once, as a resolved value.
}

On 0.3.1 the first delta "nu" does not parse, so parsePartialJson returns null and the loop skips it, which is correct. The second delta completes the buffer to null, which parses to null, which the loop reads as "not ready" and also skips. The stream ends with an empty list.

Why it matters

A model's structured answer can legitimately be a top-level null: a nullable result, an optional tool output, or an explicit "no value". A consumer waiting for a frame for that answer waits forever, because the one frame that would carry the value is the one the loop skipped.

Scope: this was only ever the top level

A null nested inside an object or array was never affected. The container parses to a non-null value, so the loop emits it and the nested null rides along inside:

Stream<String> obj() async* {
  yield '{"a":';
  yield 'null}';
}
// streamPartialJson(obj()) emits: [{}, {a: null}]

The partial buffer {"a": produces an empty map as the first frame. The second delta completes the object to {"a": null}, which parses to {a: null} and is emitted as the second frame. Both frames are non-null maps, so the value == null check never fired. The bug required the top-level value itself to be null.

The fix

0.3.2 adds an internal record type that carries presence separately from the value. parsePartialJsonResult returns a record (bool hasValue, Object? value). "Nothing decodable yet" is hasValue false. "Decoded to null" is hasValue true with value null.

The diff in lib/src/streaming.dart:

// before
final value = parsePartialJson(buffer.toString());
if (value == null) continue;
final encoded = jsonEncode(value);
if (encoded == lastEncoded) continue;
lastEncoded = encoded;
yield value;
// after
final result = parsePartialJsonResult(buffer.toString());
if (!result.hasValue) continue;
final encoded = jsonEncode(result.value);
if (encoded == lastEncoded) continue;
lastEncoded = encoded;
yield result.value;

The loop now checks hasValue to decide whether a delta produced a value, and reads result.value for the value itself. A decoded null has hasValue true, so it passes the check, flows through the change detection, and reaches the yield.

The public API did not change

parsePartialJson keeps its exact Object? contract. The new parsePartialJsonResult and its PartialJsonResult type are @internal and not exported. Nothing in the public surface changed, which is why 0.3.2 is a patch bump from 0.3.1.

Tests that shipped

The regression tests in 0.3.2 cover:

a top-level null streamed across two deltas emits a single [null] frame,
a top-level null arriving in one delta also emits [null],
ordinary object growth and a never-resolving buffer still behave as before.

The root cause: null doing double duty

null was carrying two meanings on the same value. As the return of parsePartialJson, null meant "not ready yet"; as a decoded JSON value, null meant "the answer is null". An Object? cannot tell those apart, because they are the same runtime value, so any caller that has to distinguish them is stuck.

The fix gives presence its own field. A (bool hasValue, Object? value) record has a hasValue field for "is there a value at all" and a separate value field for "what is it", so "no value yet" and "the value is null" stop sharing one representation. That is the same shape as an Option, or any two-field result: worth reaching for whenever a sentinel you return can also be a legitimate value. Here both were null, which is why they collided.

rag_kit stored the caller's metadata map by reference, then handed it back from search

Yusuf İhsan Görgel — Thu, 23 Jul 2026 16:36:41 +0000

rag_kit is a small on-device retrieval toolkit for Dart and Flutter. Its InMemoryVectorStore holds Document values and answers similarity searches over their embeddings. Version 0.3.1, published today, fixes an aliasing bug in how that store kept each document's metadata map.

The API in play

The public shape of a Document:

class Document {
  Document({
    required this.id,
    required this.text,
    required this.embedding,
    this.metadata = const {},
  });

  final String id;
  final String text;
  final List<double> embedding;
  final Map<String, Object?> metadata;
}

InMemoryVectorStore exposes two methods this post uses: Future<void> upsert(List<Document> documents) to add or replace documents, and Future<List<ScoredChunk>> search(List<double> query, {int topK = 5, double? minScore, bool Function(Document)? where}) to query. Each ScoredChunk in the result has a document and a score.

The bug

InMemoryVectorStore built each stored entry by carrying the incoming document's fields across, including the metadata map:

metadata: document.metadata,

That stored the same Map instance the caller passed to upsert. The store held a reference to the caller's map. Two things follow from that.

First, editing the caller's own map after upsert returns changes what the store holds. There is no second call into the store. The write goes through the caller's reference, and the store observes it because it is the same object.

final store = InMemoryVectorStore();
final meta = <String, Object?>{'status': 'draft'};
await store.upsert([
  Document(id: 'a', text: 'hello', embedding: [1, 0], metadata: meta),
]);

// The caller edits its own map, long after the upsert call returned.
meta['status'] = 'published';

final hits = await store.search([1, 0]);
print(hits.single.document.metadata['status']);
// rag_kit 0.3.0: prints "published". The later edit reached the store.
// rag_kit 0.3.1: prints "draft". The store kept its own copy.

Second, search returns the stored Document, and its metadata is that same map. A caller that reads a result and writes to its metadata is writing into the store. In 0.3.0 a search result is a live handle into the store's internal state.

final hits = await store.search([1, 0]);
hits.single.document.metadata['status'] = 'archived';
// rag_kit 0.3.0: silently rewrote the stored document.
// rag_kit 0.3.1: throws UnsupportedError (the returned map is unmodifiable).

The failure in 0.3.0 is silent. Nothing throws; the store's data changes and the next search returns the changed value.

The fix

Version 0.3.1 changes the one line that built the stored entry:

// before
metadata: document.metadata,
// after
metadata: Map<String, Object?>.unmodifiable(document.metadata),

Map.unmodifiable does two things here. It allocates a new top-level map, so the store no longer holds the caller's instance, and later edits to the caller's map do not reach the store. It also makes the stored map reject writes, so writing back through a search result throws UnsupportedError at the point of the write, rather than changing the store quietly.

What the fix does not do

The copy is top level only. Map.unmodifiable copies only the outer map; it does not recurse into the values. If a metadata value is itself a List or a Map, that inner collection is still the caller's object, shared and mutable. A write into a nested collection can still reach the store, and it will not throw, because only the outer map is unmodifiable, not its values.

The Document dartdoc now says so: "a store may copy the top level of metadata, but is not expected to deep-copy its values." If you keep mutable collections inside metadata and need them isolated, copy them yourself before putting them in a Document.

The regression tests

Two regression tests shipped in test/vector_store_test.dart. The first upserts a Document with a metadata map, mutates the caller's map after the upsert, runs a search, and asserts the result still carries the original value. The second takes a search result, writes to its metadata, asserts that write throws UnsupportedError, and asserts a following search shows the store unchanged.

Copy at the boundary

This root cause shows up outside vector search too. Any store, cache, or index that keeps a reference to a caller-supplied mutable collection is aliasing it: the caller and the store share one object, and either side can change what the other sees. Handing that same instance back out, the way search did, compounds the surprise, because a read result becomes a live handle into internal state.

The fix is to copy the collection where it enters the store. Copying breaks the alias, so a caller's later edits stay with the caller. Making the copy unmodifiable adds the second half: a write that used to change stored state quietly now throws where it happens, next to the code that made the mistake. The cost is one top-level map copy per stored document, and an exception on a write path that was already a bug.

Check.isValidJson Failed on Correct JSON When the Model Wrapped It in a Markdown Fence

Yusuf İhsan Görgel — Thu, 23 Jul 2026 14:14:38 +0000

llm_eval is a small Dart package for regression-testing LLM output: you write checks against a model's response, run them in CI, and read the outcome off two independent fields, passed and isError. Check.isValidJson is one of two checks shown in the README's Quick Start, and it exists for structured-output regression testing.

Until today's 0.3.1 release, that check called jsonDecode directly on the raw model output. When the model wrapped its JSON answer in a markdown code fence, which every mainstream chat-tuned model does by default, the check reported a failure even though the answer was correct and the JSON inside the fence was valid. The harness did not recognize the fence.

The repro

I ran this against a real model rather than a stub: ollama serve locally with llama3.2:3b, the same model test/ollama_e2e_test.dart already uses for end-to-end tests in this package. Prompt:

What is the capital of France? Answer with a JSON object containing a city field, formatted as a code block.

Response:

```json
{
  "city": "Paris"
}
```
This is the capital of France.

That is the right answer, and the JSON inside the fence is valid. I fed the exact string through the package at 0.3.0 as a path dependency, with no mocking involved:

passed: false
isError: false
detail: not valid JSON: Unexpected character

Same result with the README's own quick-start example, verbatim:

Check.isValidJson(where: (v) => v is Map && v.containsKey('city'))

against

```json
{"city": "Paris"}
```

passed: false. The example in the README that is supposed to demonstrate the check did not work against a real model's default output format.

Why isError: false is the part that matters

llm_eval keeps passed and isError as separate fields on purpose. The doc comment on CheckResult and the README both say the split exists so a broken harness is not mistaken for a failing model. A where callback that throws, for example, routes through describeError in lib/src/check.dart and comes back as an error result rather than a fail.

The fenced-JSON case is exactly the scenario that split is meant to catch, and it slipped through it. The harness was under-featured, and the result it reported, passed: false, isError: false, means the model got the answer wrong. The model had answered correctly; the check was the thing that failed.

For anyone running this in CI against a real endpoint, that is not a one-off. Every run where the model wraps its answer in a fence, the default for most chat models unless you force a JSON-only response mode, produces a false failure. That is noise, in a package whose reason for existing is separating real regressions from harness noise.

The maintainer already knew, informally

test/ollama_e2e_test.dart, line 79, prompts the model with:

...No prose, no code fences.

That instruction is in the test suite because I had already hit this and worked around it by asking the model not to do the thing it does by default. It never made it into the library. Anyone using Check.isValidJson against a real model, without independently discovering and copying that same prompt wording, gets chronic spurious failures, with nothing in the output pointing at the prompt as the thing to change.

The fix

lib/src/check.dart, before:

CheckResult evaluate(String output) {
  Object? decoded;
  try {
    decoded = jsonDecode(output);
  } on FormatException catch (e) {
    return CheckResult.fail(detail: 'not valid JSON: ${e.message}');
  }
  final where = _where;
  if (where == null) return const CheckResult.pass();
  // ...
}

After:

static final RegExp _fencedBlock = RegExp(
  r'```(?:json)?\s*\n?(.*?)\n?```',
  dotAll: true,
);

CheckResult evaluate(String output) {
  Object? decoded;
  var viaFence = false;
  try {
    decoded = jsonDecode(output);
  } on FormatException catch (e) {
    final match = _fencedBlock.firstMatch(output);
    if (match == null) {
      return CheckResult.fail(detail: 'not valid JSON: ${e.message}');
    }
    try {
      decoded = jsonDecode(match.group(1)!.trim());
      viaFence = true;
    } on FormatException catch (e2) {
      return CheckResult.fail(detail: 'not valid JSON: ${e2.message}');
    }
  }
  final passDetail = viaFence
      ? 'parsed after stripping a markdown code fence'
      : '';
  final where = _where;
  if (where == null) return CheckResult.pass(detail: passDetail);
  // ...where handling unchanged, now returns CheckResult.pass(detail: passDetail) on success
}

The unfenced fast path is untouched: raw jsonDecode runs first, and correct unfenced JSON never reaches the regex. Only on a FormatException does it look for a single fenced block, optionally tagged json, with dotAll so the fence can span lines, and try decoding the captured content.

There is one genuinely new failure branch: a fence that matches but whose contents still do not parse, caught as e2. It returns the same not valid JSON: message shape as the original path, so the failure text a user sees is unchanged even though the control flow reaching it did not exist before.

The detail field on a pass reached through the fallback reads 'parsed after stripping a markdown code fence'. The fix avoids silently accepting fenced JSON and presenting the input as clean. A report from this path records which route decoded the value, so when you are working out why a check passed, you can see that it went through the fence-stripping branch.

Tests

test/check_test.dart now covers:

passes on a fenced block tagged json
passes on a plain fenced block with no language tag
passes on the exact repro shape: fenced JSON followed by trailing prose after the closing fence
confirms the where callback receives the value decoded from inside the fence rather than the raw string
fails when neither the raw string nor the fenced content parses as JSON
a regression guard: plain non-JSON prose with no fence still fails exactly as before

The fix adds a fallback path and leaves the definition of valid JSON alone. Prose with no fence and no JSON in it still fails the way it always did.

I also checked it the boring way: git stash on the fix file alone, rerun the repro, passed: false, the original bug. Restore the stash, rerun, passed: true. Full round trip, no drift in the diff.

What this means if you are writing similar checks

Check.isValidJson was written against the JSON spec: does this string parse as JSON. It was not written against how models that emit JSON actually respond when you do not constrain them, which is markdown-formatted prose with a fenced block inside it.

Any check you write against "the model's output" has both of those as inputs: the format your check expects, and the format the model tends to produce when you have not forced it otherwise. A README example that looks obviously correct can still fail the moment you point it at a real endpoint, because the gap sits in the shape of string that actually arrives rather than in the check's logic.

0.3.1 is on pub.dev now.

DEV Community: Yusuf İhsan Görgel

The Biggest MCP Update Ever, Explained With a Restaurant

First: what is MCP?

The waiter is gone: MCP is now stateless

The card at the door: server/discover

The buzzer: subscriptions/listen

The question written on your receipt: MRTR

The menu photo has an expiry time: caching hints

The complaint codes on the wall

The old side door is closing

Why I am the one telling you this

What this means for you

Also changed, in one breath

Your receipt, please

The object that falls out of the Set it is still in — mutable hashCode in Dart

Why the set loses it

Two ways to be correct

Where this actually bites

My CI ran on three platforms and still could not catch this

Testing a claim about two architectures needs two architectures

How big, exactly

Where the bit goes missing

The part worth generalising

What the docs say now

The 24.8 milliseconds you pay before ffmpeg decodes a single sample

The measurement

The floor

What it actually costs you

The check that made the numbers mean anything

Run it yourself

Pinning the point you pinch: the one line behind anchored zoom

A view is a scale and a translation

Pin one point and solve for the rest

Where the focal point comes from

Two axes, no new ideas

The line, as code

Checking it holds

Where this lives in Flutter

A wrinkle: when a drag should pan and when it should dismiss

Keep this one line

A public const constructor is the back door around your factory's validation

The setup

Two doors, one object

"Just make the constructor validate itself"

The fix in 0.4.0

Honest scope: this was mostly preventive

Why this had to happen before 1.0.0

If a factory validates, close the constructor

2.75 seconds or 2 microseconds: the same regex, two engines

The measurement

Why one explodes and the other does not

A backtracking engine treats matching as a search

RE2 does not search

Why Dart's built-in RegExp is the backtracking kind

The million-character match

Using it in Dart

The honest trade-off

A finite loop in skeleton_shimmer that stopped resuming when the loop count was raised

The symptom

Root cause

The framework behavior underneath it

The fix

Two behaviors that had to keep working

The regression test

An AnimationController parked at a bound is a quiet trap

A route could write index.html outside the output directory: a path traversal fix in flutter_prerender 0.3.2

From a route to a file path

Where the routes escaped

Why a leading-slash check let them through

The fix in 0.3.2

1. Reject the dangerous shapes in normalizeRoute

2. Skip a bad crawled link instead of aborting the crawl

3. A containment check at the write boundary

What the functions do now

What still works: safe absolute links

When external input becomes a path

A resolved top-level null was dropped from streamPartialJson (stream_struct 0.3.2)

The bug

Reproducing it

Why it matters

The card at the door: `server/discover`

The buzzer: `subscriptions/listen`