DEV Community: Hirohisa Tanaka

I Want to Be Graceful

Hirohisa Tanaka — Tue, 03 Nov 2026 10:34:39 +0000

I Want to Be Graceful

I don’t want to be someone who never breaks. I want to be someone who still has room to maneuver after things break.

The takeaway

I thought about the wish to “be graceful” alongside Graceful Degradation in software design. Graceful Degradation is the idea of preserving essential functionality even when some parts become unavailable, so users can still achieve their goals.

Grace isn’t defined by perfect manners, but by the options you still have after the unexpected happens
Decide in advance what matters and what can be sacrificed
Don’t just recover on your own—let the people around you know what’s happening and what to do next

“Implementing this in life” is a metaphor. Humans can’t be run on TypeScript. But the perspective of designing how things fail can also be useful when thinking about how people behave.

Grace is designed room to maneuver. It’s not just the ability to keep things on schedule. It’s the ability to protect what matters when things go off course and give the people around you enough information to make their own decisions.

This article expands on the content of my five-minute lightning talk, “I Want to Be Graceful,” with a definition of Graceful Degradation and some additional design context. It’s written to be accessible to both engineers and people unfamiliar with technical terminology.

1. I wanted to be graceful

Lately, I’ve been listening to classical music. When you listen to music every day, it can start to seem as though not only the sound, but also the posture and gestures of the people listening, are becoming more refined.

That made me think, “I want to be graceful too.” Someone who doesn’t flinch when they spill tea, responds calmly to an unexpected message, and doesn’t let anything that happens disrupt the mood of the room.

I’m not trying to claim that classical music makes people graceful. It’s just where this talk began. When I thought about my ideal person, the first image that came to mind was “someone who doesn’t fall apart, no matter what happens.”

2. You can’t measure grace on the happy path

It’s not that hard to behave thoughtfully when things are calm. You have time, things are going according to plan, and the other person is relaxed too.

The hard part is when unexpected things pile up. Plans change. The connection drops. Your presentation slides break right before you’re due to present. If you raise your voice, stop making decisions, and spread anxiety to everyone around you, your usual thoughtfulness can disappear in an instant.

What you need then isn’t the performance of keeping a straight face. It’s enough room to choose your next move.

You can break grace down into three parts:

Composure: keeping one more option open
Judgment: deciding what to protect and what to let go
Consideration: letting the people around you know what’s happening and what comes next

3. What is Graceful Degradation?

MDN describes Graceful Degradation as a design philosophy that creates the best experience in modern browsers while still providing essential content and functionality in older browsers.

For example, instead of leaving the entire screen blank when a new API isn’t available, you can preserve the main operation using another method. The experience may be less polished, but users can still achieve their goal. That’s graceful degradation.

Microsoft’s reliability guidance also describes the idea of providing a degraded mode that preserves critical operations when a component is unavailable. Detect the failure, switch to an alternative path, and let users know what has changed. That’s all part of the design.

flowchart LR
    A[想定外の障害] --> B{重要な経路か}
    B -->|いいえ| C[非本質的な機能を縮退]
    B -->|はい| D[代替経路へ切り替え]
    C --> E[本質的な機能を継続]
    D --> E
    E --> F[状況と次の手を伝える]

The important thing is not to try to preserve everything. Decide what to cut. Decide what to keep. Azure’s Throttling Pattern, for example, describes stopping or degrading nonessential features to preserve resources for critical ones. It’s a design that gives up a complete response in favor of availability.

If you distinguish between primary operations, tasks that can be retried later, and displays that don’t directly affect users when they fail during the design stage, you won’t have to panic during an outage and choose between “stop everything” and “let everything through.”

For example, an ordering service might keep product browsing and saving items to a cart available, defer inventory recalculation and product recommendations, and hold off on payment until it can be verified safely. The priority of each operation is decided based on its purpose.

4. Don’t leave exceptions as exceptions

When writing code, it’s tempting to build the happy path first.

Unexpected Event → Panic → Crash

With this flow, the system’s job is over the moment something unexpected happens. For a person, it’s like ending a conversation as soon as plans change.

Graceful Degradation leaves a path open even after something unexpected happens.

Unexpected Event → Understand → Adapt → Respond

First, understand what happened. Next, decide what to protect. Decide. Keep. Keep only what’s essential to that goal, and switch to a different response.

You can’t do everything. Keep. Cut. Communicate.

This doesn’t mean “accept anything.” Graceful design has conditions for switching paths. For example, if the database goes down, stop writes and switch to read-only mode; if an external API is slow, return cached data.

5. Let’s write ElegantPerson.ts

In my talk, I represented human behavior in TypeScript.

interface ElegantPerson {
  composure: boolean
  consideration: boolean
  adaptability: boolean
}

function handle(event: UnexpectedEvent) {
  try {
    return respondElegantly(event)
  } catch {
    return respondWithDignity()
  }
}

This isn’t an executable implementation. Since neither UnexpectedEvent nor respondElegantly is defined, it won’t build as-is.

Even so, it makes the design questions visible. Do you have composure? Are you considerate of others? Can you change your response to fit the situation? And if your first response fails, do you have an alternative that preserves your dignity?

Unfortunately, human code can’t be type-checked before it goes into production. Inputs like lack of sleep, stress, and running out of time can arrive without warning. That’s why it’s worth thinking not about an implementation that never fails, but about what you can preserve when it does.

6. You can share grace with others

When a system degrades, notifying users is important. If the functionality changes without an explanation, users can’t tell whether something is broken or they did something wrong.

It’s the same for people. When you’re running out of room to maneuver, silently trying to handle everything on your own takes options away from the people around you.

Don’t stop. Don’t hide it.

“I can’t share the slides right now. I’ll continue verbally.”

That one sentence explains the situation and offers an alternative path. It’s not perfect. But the event can continue.

A graceful person isn’t someone who never lets anything happen. They’re someone who doesn’t hide what happened and can offer what’s possible next. They don’t just protect their own composure—they can share a little of it with the people around them, too.

7. Conclusion

We can’t eliminate the unexpected. Differences between browsers, outages of external services, and oversleeping aren’t going away.

So design ahead of time. What’s essential? How much can be degraded? Under what conditions should you switch to an alternative path? And what should you tell the other person?

Graceful Degradation is a technical term for making systems more resilient. If we use it to think about human behavior, we might put it this way:

Grace isn’t about never breaking. It’s about still having room to maneuver after things break.

I’ll start by learning how to make tea.

Stay Graceful.

References

MDN: Graceful degradation — Definition of a design philosophy that preserves essential functionality
W3C: HTML Design Principles — Fallbacks for older or less capable user agents
Microsoft: Architecture strategies for self-healing and self-preservation — Degraded modes, alternative paths, and user notifications
Microsoft: Throttling Pattern — The idea of protecting critical features by dropping nonessential ones

Cloudflare Agents Now Supports Pi 1.4: Testing Agent Interruption, Recovery, and Persistence

Hirohisa Tanaka — Sun, 01 Nov 2026 14:32:00 +0000

The interrupted Agent resumed correctly from its last checkpoint. That’s why the side effect happened twice.

Article takeaway

Now that the Cloudflare Agents SDK supports Pi 1.4, I stopped an Agent running on a Durable Object and measured how much of its conversation history, tasks, and tool execution could be recovered. The recovery mechanisms worked as expected, but recovering an Agent and preventing duplicate external side effects are two different things.

I confirmed Hibernation and Parked Tasks, introduced in Pi 1.4, on a real Durable Object
replay: "safe" does not check idempotency. Apply it to a non-idempotent tool, and the same side effect happens twice
Storage Error Recovery does not save an in-progress call; it reopens Pi starting with the next operation
agents@0.30.0 has a known bug where a task waiting to retry cannot wake while another task is running. Use 0.30.1 or later

What I observed	Result
Conversation history after restart	Restored
Completed tasks	Not executed twice
Idempotent tool marked `safe`	Re-executed, but side effect occurred once
Non-idempotent tool marked `safe`	Side effect occurred twice
`unsafe` tool	Not automatically re-executed, and did not complete
Hibernation	Resumed on a different instance while waiting

The test code is here: https://github.com/tanahiro2010/slides/tree/main/slides/slides/Cloudflare%20Agents%E3%81%8CPi%201.4%E3%81%AB%E5%AF%BE%E5%BF%9C%E3%81%97%E3%81%9F%E3%81%AE%E3%81%A7%E3%80%81Agent%E3%81%AE%E4%B8%AD%E6%96%AD%E3%83%BB%E5%BE%A9%E6%97%A7%E3%83%BB%E6%B0%B8%E7%B6%9A%E5%8C%96%E3%82%92%E6%A4%9C%E8%A8%BC%E3%81%99%E3%82%8B/sandbox

And here’s the main point I want to make up front.

replay: "safe" does not make a tool safe. It only tells Pi, “If this tool is interrupted, it’s okay to run it again.” The tool implementation must guarantee that its side effects are truly idempotent, and that an external API will not process the same request twice.

This article expands on the talk “Cloudflare Agents Now Supports Pi 1.4: Testing Agent Interruption, Recovery, and Persistence” with test procedures, measured results, and failed measurements that I couldn’t cover in the presentation. It’s for people using Cloudflare Agents and Pi Durable to interact with external APIs and databases.

1. Breaking down the four items in “Pi 1.4 support”

On October 22, 2026, Cloudflare announced Pi 1.4 support in the Agents SDK. The changelog lists four items:

Hibernation
Parked Tasks
Storage Error Recovery
Model Stream Retry

At first, I thought all four were new features in Pi 1.4. But tracing the packages and change history revealed that they came from two different layers.

Changelog item	Where the change actually comes from
Hibernation	Agents SDK wiring for Pi 1.4 `sleeping` tasks
Parked Tasks	Agents SDK exposes a Pi 1.4 feature
Storage Error Recovery	A fix in the Agents SDK, independent of the Pi version
Model Stream Retry	A fix in the Agents SDK, which also works with Pi 1.3

In particular, the Model Stream Retry PR says that the behavior was verified with both Pi 1.3.0 and Pi main. So comparing Storage Error Recovery and Model Stream Retry between Pi 1.3 and 1.4 is the wrong axis. The relevant comparison is agents@0.29.0 vs. agents@0.30.x.

Vendor changelogs group changes into units that are easy for users to understand. But when investigating an incident, you need to identify which package and layer is responsible.

2. The roles of Pi, PiHarness, and Lifecycle

This setup has three layers.

Layer	Responsibility
Pi Durable	Agent execution loop, tasks, checkpoints, and replay
PiHarness	Connects Pi to Durable Object SQLite and startup processing
Lifecycle	Runs long-running work on a Durable Object and wakes it when needed

Pi Durable is not a Cloudflare package. It’s available as @earendil-works/pi-durable and integrated into Durable Objects by the Agents SDK’s PiHarness.

The important point is that persistence and resumption are separate features.

Conversation history and tasks are stored in SQLite tables prefixed with pi_
Resuming sleeping tasks is handled by Lifecycle Wake jobs and Durable Object Alarms

Having data saved is not enough to resume if there’s no mechanism to wake the task. Conversely, even if a task can resume, it won’t know where to continue from without a checkpoint. In this test, I kept these two mechanisms separate.

The Pi Durable design article puts it this way:

every step of a run is a task that stores a checkpoint before it moves on.

These checkpoints are the foundation for preventing completed tasks from running again after a restart.

3. Persist the observations first

When measuring failure recovery, the first thing to build is not the system under test but the recording mechanism. Writes to a Durable Object are not necessarily committed to disk the moment they’re issued.

The test recorder writes events to SQLite and then usually calls ctx.storage.sync(). Immediately afterward, it calls ctx.abort() and compares whether the events remain after restart.

Recording method	Restarted	Rows remaining after restart
With `sync()`	Yes	1
Without `sync()`	Yes	0

In both cases, the instance ID generated in the constructor changed. The same instance did not keep running; a newly created instance read from SQLite.

ctx.abort() is different from a regular throw. It cannot be caught in application code and immediately resets the Durable Object. If you use a regular exception to inject a failure, you’ll be measuring error handling in the same instance, not Agent recovery.

After confirming this foundation, I recorded all subsequent events with sync(). I did not treat observations missing from the logs as evidence of recovery.

4. Conversation history and tasks survive a restart

I ran an Agent that executes a tool once and called ctx.abort() after it completed to stop the Durable Object. Then, after the restart, I read the transcript and events.

Observation	Before restart	After restart
Instance identifier	—	Changed
Transcript entries	5	5
Tool execution started	1	1
Side effects	1	1

The completed task did not run twice. Submitting twice with the same operationId returned accepted: true the first time and accepted: false the second time. With a different ID, it returned accepted: true, so submit itself was not broken.

This shows Pi Durable using checkpoints and submit identifiers to protect completed work.

5. The Agent keeps running after the client disconnects

Next, I extended processing time through model retries and disconnected the WebSocket midway through. I checked whether execution continued after the client was gone.

The run eventually reached done. There were three model calls: two failures and one success. The instance ID did not change before or after the disconnect.

This was not a case of “crashing and recovering.” It showed that Agent execution did not depend on the client connection.

After reconnecting, I could reconstruct the current state from the snapshot. However, I could not use a cursor to replay events from the middle of the stream that arrived during the disconnection. The event stream can be used to track state, but it is not a substitute for a history stream.

6. Parked Tasks stop crash loops

I repeatedly triggered ctx.abort() at the same point and tested with restartLimit reduced to 2.

How it stopped	Failure triggers	Instances created	`pending()`	Next Alarm
`ctx.abort()`	2	2	`parked`	None
Regular exception	1	0	Empty	None

A regular exception does not reset the Durable Object, so it does not count toward the restart limit. To reach Parked, you need a failure that actually causes a restart.

A Parked task will not keep waking the Durable Object if left alone. There are two ways to handle it manually.

Operation	Return value	`wait()`
`session.retry()`	`true`	`done`
`session.abort()`	`ok`	`unanswered` / `aborted`

retry() retries the task; abort() abandons it. This design does more than stop a crash loop: it lets an operator decide whether to resume or abandon the task.

Also, even when a tool emitted progress eight times via api.output(), the restart counter did not reset. Pi considers a task’s transition to its next committed state to be progress, not tool output. If a single unfinished tool keeps emitting output, the crash-loop limit is not reset.

7. Storage Error Recovery takes effect on the “next operation”

Storage Error Recovery lets Pi be reopened after a storage error. I wrapped Storage in a Proxy and injected two kinds of errors:

Return an arbitrary error from methods such as commit()
Return a StorageRequestError from a read

In both cases, the call already in progress failed. But the next submit() succeeded, and the run eventually reached done. For a fatal Storage error, the factory was called twice instead of once, but the Durable Object’s instance ID did not change.

So this is not Durable Object crash recovery. PiHarness removes the broken Pi instance from its cache and reopens Pi on the next operation or the next step of a Wake job.

The call already in progress is not saved. The specification also says that an in-progress call fails with SessionFailed. The factory must be written so it can initialize correctly every time it runs.

8. `replay: "safe"` does not protect side effects

This is the central finding. I created four types of tools and recorded their execution start, side-effect commit, and completion separately. I stopped the Durable Object immediately after the side effect was committed and compared what happened after restart.

Tool	`replay`	Idempotent	Execution started	Side effects	Completed
`write_record`	`safe`	Yes	2	1	1
`bump_unsafe`	Unspecified	No	1	1	0
`bump_safe_unguarded`	`safe`	No	2	2	1
`bump_safe_guarded`	`safe`	Yes	2	1	1

write_record writes the same value, so running it twice does not change the result. bump_safe_unguarded simply increments a counter, so each execution changes the result. When I marked this tool safe, Pi trusted that declaration and ran it again, committing the side effect twice.

On the other hand, bump_unsafe is not automatically re-executed. In the case where the Durable Object crashed after the side effect was committed, the side effect remained once, but the tool did not complete. The Agent resolves the run by passing the interrupted tool result to the model.

An interrupted tool does not get a special transcript entry. It uses the regular pi.tool-result entry, but its content changes to something like this:

<harness>
[error] Tool bump_unsafe was interrupted and may have partially run
</harness>

This is plain text telling the model that the tool may have run partially. Whether the model calls the same tool again is up to the model. In three tests with a real model, it did not call the tool again, but that’s just one model, one prompt, and three trials, so I won’t generalize from it.

I added an idempotency key to bump_safe_guarded. It was re-executed, but the second run checked the key and skipped the side effect, keeping the total number of commits to one.

The takeaway is clear. Pi will not warn you if you choose safe incorrectly. If your tools interact with external APIs, payment systems, email, databases, and so on, you need to implement idempotency keys or deduplication separately from the safe setting.

9. Model Stream Retry checks error messages

Model Stream Retry treats an interrupted model stream as a temporary error and retries the entire turn. Reading the package revealed that it uses a regular expression to match the error text.

I made the same number of attempts fail and changed only the error message.

Error message	Result	Model calls
`The stream ended before the model finished its answer.`	`unanswered`	1
`The stream ended without the model finishing its answer.`	`done`	3
`Model stream stalled: no data received for 60s.`	`unanswered`	1
`Model stream timed out: no data received for 60s.`	`done`	3
`insufficient_quota: the account has no remaining credit.`	`unanswered`	1

For messages that trigger a retry, there were three calls: two failures and one success. In other words, a retry starts a new model request; it does not continue a partial stream.

Even when I set baseDelayMs to 100 seconds, the wait was capped at about 60 seconds. That’s because the default maxAgentDelayMs is 60,000 milliseconds. Increasing the setting does not mean it will wait indefinitely.

10. Hibernation resumes on a different instance while waiting

For the Hibernation test, I first compared alarm times. But in local workerd, the alarm timings matched whether or not I passed onWake. I was measuring the wrong thing.

The essence of Hibernation is not the alarm time, but whether the Durable Object can be evicted from memory while waiting. So I deployed it and recorded the instance ID in the constructor to see which instance ran the retry.

When I passed onWake, the sequence was:

model_error@old-instance
→ instance_started@new-instance
→ model_request@new-instance

Without onWake, the sequence was:

model_error@same-instance
→ model_request@same-instance

`onWake`	Instance that ran the retry
Passed	Different instance
Not passed	Same instance

I did not send any requests while the retry was waiting. Touching the object would wake it and prevent me from observing eviction.

In-progress work and a sleep while waiting to retry are different states. While work is active, the heartbeat Alarm is rescheduled every 30 seconds. During sleep, the next Alarm is scheduled for the time of the earliest task to wake. Mixing these two up can lead to misreading the Hibernation test results.

11. Reproducing the `agents@0.30.0` bug

I tried to start testing with the officially recommended agents@0.30.0. But this version has a known bug: a task waiting to retry will not wake while another task is running.

I ran these two tasks concurrently in one Harness:

Session A: run a tool that takes 60 seconds
Session B: return an error that triggers a retry and enter a 12-second backoff

	B running alone	With concurrent work
`agents@0.30.1`	12 seconds	12 seconds
`agents@0.30.0`	12 seconds	57 seconds

With 0.30.0, B’s retry was blocked until A completed. With 0.30.1, B resumed after the expected 12 seconds, even while A was running.

The cause is also clear from the package diff. Version 0.30.0 checked only whether Pi was active. Version 0.30.1 uses the sleep deadline wake.at as the next wake-up deadline and calls pi.resume() when it is reached.

This isn’t meant to be alarmist. It’s a concrete example of PiHarness being labeled Beta. If you’re testing Pi 1.4 Hibernation, you need to use agents@0.30.1 or later.

12. Once you upgrade to Pi 1.4, you can’t go back to 1.3

Pi 1.4 updates the SQLite schema for session storage, so you cannot roll back to Pi 1.3.

After running one turn with Pi 1.4, the schema version was 2. Comparing the migration definitions in the packages shows this difference:

Version	Migrations
`pi-durable@1.3.0`	Version 1 only
`pi-durable@1.4.0`	Version 1 and version 2 `sleepingStatus`

The Pi 1.3 migration runner returns an error if it encounters a newer schema version it does not support. The added sleepingStatus is the sleeping task state that supports Pi 1.4 Hibernation.

In other words, being able to evict a Durable Object and losing the ability to roll back are not separate changes. They are two sides of the same schema change.

When comparing Pi 1.4 and 1.3, do not reuse the same Durable Object. Use separate names for experiments and treat migrations as one-way.

13. What I learned by rerunning the tests

I did not publish the initial test results as-is. After rebuilding the controls, I revised or held back three claims.

WebSocket event loss

At first, it looked like a slow event listener was missing events. But the cause was that I closed the WebSocket after eight seconds. When I extended the drain time to 30 seconds, the event counts matched even with the slow listener.

Defining progress

I had assumed that updating my own counter meant Pi had made progress. Even with a control that called api.output() eight times, an unfinished tool still became Parked. Progress means that the task committed a state, not that the tool emitted output.

A 19-minute model stream

I streamed data for about 19.2 minutes using a faux Provider inside a Worker, and it completed with one model call. However, this did not measure keeping an HTTP connection to an external model API open for 19 minutes. Since it does not disprove the official limitation that requests lasting more than 15 minutes may be disconnected, I’m leaving this conclusion open.

When testing failure recovery, “I got a result” is not enough. You need controls to rule out possibilities such as the failure never occurring in the first place or the observation side closing the connection too soon.

14. Conclusion

The Cloudflare Agents and Pi 1.4 recovery mechanisms worked in practice. Conversation history could be restored after a restart, completed tasks were not executed twice, crash loops stopped with Parked Tasks, and an Agent waiting to retry could resume on a different instance through Hibernation.

But Pi protects the Agent’s execution state. It does not automatically make your external side effects exactly-once.

When implementing this, keep these points in mind:

Add idempotency keys or deduplication for external operations
Set replay: "safe" only for tools you can prove are safe to execute twice
Marking a tool unsafe does not undo a side effect that has already been committed
Write your factory assuming Storage Error Recovery may call it multiple times
If you use Hibernation, use agents@0.30.1 or later
You cannot roll back a Durable Object upgraded to Pi 1.4 to Pi 1.3

If I had to distill one lesson from this test, it would be this:

“Recovered” and “completed without duplicates” are two different claims.

References

Cloudflare Changelog — Agents SDK now supports the latest Pi 1.4 release — The four items announced as Pi 1.4 support
Cloudflare Docs — Pi — Official documentation for PiHarness, Recovery, and Hibernation
Cloudflare Docs — Pi Extensions — Tool replay settings and behavior during recovery
agents CHANGELOG — Changes in 0.30.0 / 0.30.1
cloudflare/agents#2683 — Known bug involving onWake and concurrent tasks
pi-durable CHANGELOG 1.4.0 — Pi 1.4 sleeping tasks and schema migration
Pi Durable design article — Checkpoint and task execution design

MCP Step-Up Authorization vs. OAuth Incremental Authorization: What Actually Changes?

Hirohisa Tanaka — Thu, 22 Oct 2026 03:58:00 +0000

MCP Step-Up Authorization vs. OAuth Incremental Authorization: What Actually Changes?

“There are no zones.” There were three.

TL;DR

When Cloudflare announced step-up authorization for its API MCP Server, I wanted to know how it differed from Google OAuth's Incremental Authorization. I read the specs, wrote my own MCP client, and sent 128 requests to the live service. The additional authorization itself is still ordinary OAuth. The difference is a path for the server to tell the client, “You don't have enough permission.”

The client remembers previously granted scopes. Cloudflare's authorization server does not carry over previously granted scopes outside the baseline set. This is the opposite of Google's include_granted_scopes behavior.
But Cloudflare's server remembered them too. The scope in a 403 challenge followed the scopes granted to that token. That is the approach MCP removed in the 2026-07-28 specification.
The challenge path did not cover every operation. On the same server, some insufficiently authorized operations returned a 403 challenge, while others returned 200 with an empty list.
- I reported the third finding to Cloudflare, and it was fixed that same day. The follow-up is in §13.

Here is what happened when I called the same APIs before and after granting scopes:

Operation	Before granting scopes	After granting scopes
List zones	0 items	3 items
List Workers scripts	0 items	12 items
List D1 databases	403 challenge	5 items

Test code: GitHub repository

Let me state the main point upfront.

Step-up Authorization does not introduce a new way to authorize. It introduces a way to communicate that a scope is missing. In a traditional web app, developers know which feature needs which scope. With MCP, an AI chooses tools, so the client may not know in advance. The server has to notice that permission is missing, and it needs a way to tell the client. When that path works, a client can start with minimal permissions. When it doesn't, the AI simply reports that something “doesn't exist.”

This article expands on my lightning talk, “How Is MCP Step-up Authorization Different from OAuth Incremental Authorization?”, with measurements I couldn't fit into the talk and the details of a conclusion I had to retract once. It is for readers who know the basics of OAuth 2.0 and may build MCP servers.

1. The third step in a three-part rollout

On October 19, 2026, Cloudflare posted this in its Changelog:

Grant only the required scopes when you connect, then authorize more on demand as your agent performs a task. When a tool call needs a scope you have not granted, the server returns an insufficient_scope challenge naming it, and your MCP client asks you to approve it. Scopes you already granted are kept.

Start with the minimum, then add permissions when needed. When I read that, I couldn't tell how it differed from include_granted_scopes=true, which I already use in my own projects. That question started this investigation.

The announcement was not an isolated change. It was the third step in a rollout:

Date	Event
August 22, 2026	Wrangler and the API MCP Server added optional scopes and “Edit Permissions” on the consent screen
October 1, 2026	`workers-oauth-provider` v1 made step-up possible with a one-line `insufficientScope()` call
October 19, 2026	The API MCP Server added step-up authorization

The August Changelog ended with this instruction:

If a command or tool call needs a scope that you declined, reauthorize the client and grant that scope.

At that point, if you declined a permission, you had to reconnect manually. The ability to grant fewer permissions came with extra friction. The October change removed that manual step.

2. Two versus 384

Cloudflare's MCP server publishes two different scopes_supported lists. They have the same name, but different RFCs define them for different purposes.

curl -s https://mcp.cloudflare.com/.well-known/oauth-protected-resource/mcp
curl -s https://mcp.cloudflare.com/.well-known/oauth-authorization-server

Metadata	RFC	Count	Contents
Protected Resource Metadata	RFC 9728	2	`user:read`, `account:read`
Authorization Server Metadata	RFC 8414	384	`dns.write`, `zone.write`, `workers-r2.read`, …

The first list says what is minimally needed to access this resource. The second is the full catalog of scopes this authorization server can issue. The MCP specification describes the first as the minimal set of scopes necessary for basic functionality.

Without authentication, the server returns a 401 naming those two scopes:

HTTP/2 401
www-authenticate: Bearer realm="OAuth",
  resource_metadata="https://mcp.cloudflare.com/.well-known/oauth-protected-resource/mcp",
  scope="user:read account:read"

The gap between 2 and 384 is why this feature exists. Without step-up, the client has to choose from 384 scopes up front. Request too few and things don't work; request too many and you overgrant access. Starting with just two scopes is practical only if you can add more when you discover you need them.

3. Step-up builds on RFC 6750

In the MCP specification, step-up starts with a 403 insufficient_scope response:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
                         scope="files:write",
                         resource_metadata="https://mcp.example.com/.well-known/oauth-protected-resource",
                         error_description="File write permission required for this operation"

MCP did not invent this error code. It was defined in RFC 6750 §3.1 in 2012:

insufficient_scope — The request requires higher privileges than provided by the access token.

What MCP adds is the procedure that turns this response into reauthorization:

Parse WWW-Authenticate.
Determine the required scopes as “the scopes requested last time ∪ the scopes in the challenge.”
Reauthorize. This is the normal OAuth authorization-code flow.
Retry the original request.

Compared with Google OAuth Incremental Authorization, the differences come down to three questions:

	Google Incremental Authorization	MCP Step-up Authorization
Who notices that more access is needed?	The application, before it calls the API	The server
How is the missing scope communicated?	No challenge; the app already knows	`WWW-Authenticate: scope="…"`
Who remembers previously granted scopes?	The authorization server (`include_granted_scopes=true`)	The client
How does reauthorization work?	OAuth authorization-code flow	The same flow

The third row cannot be resolved by reading the specification alone. The Changelog says “Scopes you already granted are kept,” but leaves out the subject. The client may be taking a union, or the authorization server may be remembering the earlier grant. Both interpretations fit. Determining which one was true in the live service became the center of my test.

Terminology: baseline
In this article, baseline means the minimal scopes named by Protected Resource Metadata (user:read and account:read) plus offline_access. Cloudflare's consent screen presents these three every time, regardless of previous grants.

4. It was not a new feature in the 2026-07-28 spec

The Changelog linked to step-up in MCP 2026-07-28, so I assumed it was new. It wasn't. The “Step-Up Authorization Flow” section was already in the 2025-11-25 specification. It was absent before 2025-06-18.

What changed in 2026-07-28 was who creates the union of scopes:

Specification	Who creates the union?
2025-11-25	The server
2026-07-28	The client

The 2025-11-25 version gave servers three choices: Minimum, Recommended, and Extended. All three assumed that the server would include previously granted scopes in the 403 challenge. The 2026-07-28 version removed all three choices.

The reason is in Issue #2349:

This contradicts the RFC, creates an impossible requirement for stateless servers, and leads to infinite re-authorization loops in practice.

TypeScript SDK Issue #1582 demonstrates the loop. Imagine a server where initialize requires init, while tools/list requires mcp:tools:read:

sequenceDiagram
    participant C as MCP Client
    participant S as MCP Server
    C->>S: tools/list (token: init)
    S-->>C: 403 scope="mcp:tools:read"
    Note over C: Overwrites _scope; loses init
    C->>S: tools/list (token: mcp:tools:read)
    S-->>C: 200
    C->>S: initialize (token: mcp:tools:read)
    S-->>C: 403 scope="init"
    Note over C: Overwrites _scope again; loses mcp:tools:read
    Note over C,S: The loop continues

If a 403 faithfully returns only the scope required by that operation, the previous permission disappears as soon as the client overwrites its scope list. A union is not just good manners; it prevents this failure mode.

5. I wrote a client without the SDK

I did not use @modelcontextprotocol/client for this test. As soon as that library sees a 403, it calls computeScopeUnion() and automatically unions the scopes before reauthorization:

function computeScopeUnion(...scopes) {
    const seen = new Set();
    for (const scope of scopes) {
        if (!scope) continue;
        for (const token of scope.split(/\s+/)) if (token) seen.add(token);
    }
    return seen.size > 0 ? [...seen].join(" ") : void 0;
}

That is a correct implementation. But it means I cannot test reauthorization without a scope union. It would be impossible to isolate who is preserving the previous scopes. So I wrote a minimal client that manually performs OAuth and MCP requests. Being able to choose the requested scopes each time was essential to this test.

I did not need to pre-register a client. Cloudflare's authorization server supports Dynamic Client Registration, so the script can register itself as a public client. It does not receive a client_secret.

The transport does not throw on HTTP errors. A 400 or 403 is an observation, so the client records and returns the status, headers, and body instead of swallowing them. Every request passes through one hook and is logged as one line of JSON per round trip. Secrets are replaced with fingerprints, not removed entirely:

"access_token": { "_redacted_len": 82, "_sha256_16": "184d68d85f68caab" }

Replacing a value with <redacted> makes it impossible to show whether the same token was sent repeatedly or a new one was issued each time. A fingerprint shows both without disclosing the token. I later used matching fingerprints sent to two resources as evidence that they were the same token.

Two requested scopes, three granted

The consent process has two screens. First, you choose a preset that includes “Minimal.” Then you see a breakdown of the requested permissions. The Changelog's instruction to “choose Minimal on the consent page” refers to the first screen.

The second screen has REQUIRED and ADDITIONAL ACCESS sections. Required permissions cannot be removed. Individual optional permissions can be unchecked through Edit Permissions. This is where the optional-scope change from August appears. I show the actual screen in §7.

I requested two scopes, user:read account:read, but received three:

Requested: user:read account:read
Granted:   user:read offline_access account:read

I briefly wondered why I had an offline_access scope I never requested. The screen explained it: Background Access was listed as REQUIRED. This made a basic lesson matter from the first test: record requested scopes and granted scopes separately.

6. The challenge `scope` included the baseline

To trigger 403 responses, I tried read-only endpoints systematically. The OpenAPI specification returned by the search tool includes x-api-token-group, whose description says:

API token permissions the endpoint accepts (any one); OAuth scopes have the same names

This lets you derive the mapping between scopes and endpoints from the server itself. For example, GET /zones lists Zone Zone Read.

When I called an operation requiring a scope I did not have, I got this challenge:

HTTP/2 403
WWW-Authenticate: Bearer realm="OAuth", error="insufficient_scope",
  scope="user:read account:read workers-r2.read",
  resource_metadata="https://mcp.cloudflare.com/.well-known/oauth-protected-resource/mcp",
  error_description="This operation needs the workers-r2.read scope"

The scope includes the baseline. This is where Cloudflare's implementation and its own documentation diverged from the MCP specification:

Source	What to include in the 403 `scope`
MCP 2026-07-28 specification	Only the scope needed by the operation is sufficient; including previous scopes is not required
`workers-oauth-provider` documentation	Include all scopes, including the baseline
Live service	The latter

The error_description explicitly names the missing scope, which is also helpful for a human reading the response.

7. Who remembers? I got this wrong once

This is the central question. I requested only d1.read, deliberately dropping the three scopes I already had:

Requested: d1.read
Granted:   d1.read user:read offline_access account:read

The three scopes I had not requested were still there. I almost wrote, “The authorization server preserves previous grants.”

That was wrong. There were three possible explanations, and this observation could not distinguish between them:

The authorization server preserved previously granted scopes.
I had included scope: "user:read account:read" during DCR registration. That was my own confounding factor.
The resource simply adds its baseline scopes by default.

I had introduced the second confound myself. So I created a control: a brand-new client with no previous grants, registered with only d1.read, and opened the same consent screen.

The screens were identical: four permissions, User Read and Background Access under REQUIRED, and D1 Read and Account Read under ADDITIONAL ACCESS. Account Read appeared even though this client had never been authorized before.

So explanation 3 accounted for it. I retracted my conclusion.

I redesigned the test: start with a non-baseline scope, d1.read, then request only workers-r2.read. The default baseline could no longer explain the result.

D1 Read was absent from the consent screen, even though it had been granted moments earlier.

After approval, the grant was:

Requested: workers-r2.read
Granted:   workers-r2.read user:read offline_access account:read

d1.read was gone. I verified the behavior rather than relying on the text alone: the D1 list endpoint returned a 403 challenge again. The capability itself had been removed.

Cloudflare's authorization server does not carry over previously granted scopes outside the baseline.
The Changelog's statement that “Scopes you already granted are kept” is true because the client creates a union. That is structurally the reverse of Google's include_granted_scopes, where the authorization server combines the scopes.

8. The server remembered them too—the approach the spec dropped

I changed the scopes in the token and observed the challenge several times:

Scopes held	Operation	Challenge `scope`
Baseline only	List R2	`user:read account:read workers-r2.read`
Baseline + `workers-r2.read`	List D1	`user:read account:read workers-r2.read` `d1.read`
Baseline + `workers-r2.read`	List KV	`user:read account:read workers-r2.read` `workers-kv-storage.read`

The challenge was not a fixed baseline. It followed the scopes granted to the token. In other words:

challenge.scope = scopes already granted to token ∪ scopes required by operation

This is the “Recommended approach” from the 2025-11-25 specification—the approach removed in 2026-07-28. Issue #2349 said this was “impossible” for stateless servers because the server needs to know what scopes the token contains to build the union. Cloudflare shares state between its authorization server and resource server, so it does not have that limitation.

One important consequence is that older clients keep working. @modelcontextprotocol/sdk@1.32.1 overwrites _scope in its 403 handler:

if (error === 'insufficient_scope') {
    if (scope) {
        this._scope = scope;   // Overwrites the value; previous scopes are lost
    }

That is exactly the condition for the loop in §4. It still works against Cloudflare because the server builds the union on the client's behalf. The specification puts the responsibility on the client, but this implementation currently does both.

9. “There are no zones”

While testing endpoints systematically, I found operations that did not return a 403:

Operation	Required scope	Result
R2 / KV / D1 / Queues / Images	Each resource's `*.read` scope	403 + challenge
List zones	`zone.read`	200 + empty list
List Workers scripts	`workers-scripts.read`	200 + empty list
`/user/tokens`	Not in the catalog	403 in the tool result text

For the two middle rows, I could not initially tell whether permissions filtered the results or the account really had zero items. I granted zone.read and workers-scripts.read, then repeated the same calls:

List zones:             0 items → 3 items
List Workers scripts:  0 items → 12 items

The resources existed in the account. It was the same account and client; I changed only the scopes.

These operations fall outside the step-up path. Since they do not return a 403, the client does not learn that it lacks permission. It never gets a chance to ask the user for additional authorization. The AI says, “There are no zones,” and the conversation ends there.

/user/tokens fails differently:

Cloudflare API error: GET /user/tokens returned HTTP 403: 9109: Unauthorized to access requested resource. No OAuth scope covers this endpoint, so OAuth connections cannot use it. Connect with an API token that has one of these permissions instead: API Tokens Write, API Tokens Read.

There is no corresponding OAuth scope in the catalog, so there is no way to step up. This is an honest implementation: the reason is returned as text that both the AI and the user can read.

Within one server, I found three different ways an authorization failure can be represented. This difference matters when you design how to give an agent access. Only operations that return a challenge can recover on their own after starting with minimal permissions.

10. Refresh cannot add scopes

The reason additional authorization has to return to the browser is in RFC 6749 §6: a refresh token cannot be used to broaden its scope. I tested it directly:

Request	HTTP	Granted scopes
Omit `scope` (control)	200	Same original seven
Broaden (`workers-kv-storage.read` added)	200	Same original seven
Narrow (request baseline only)	200	Same original seven

The broader request follows the RFC. The extra scope is silently ignored rather than rejected. I confirmed this behaviorally too: the KV list still returned a 403.

The narrowing result surprised me. RFC 6749 §6 does not prohibit narrowing, and the workers-oauth-provider docs say, “Token and refresh requests can only narrow the grant.” In the live service, the request was ignored and d1.read still worked.

The library source implements narrowing correctly:

let tokenScopes = this.downscope(body.scope, grantData.scope);

private downscope(requestedScope, allowedScopes) {
  if (!requestedScope) return allowedScopes;
  return requestedScopes.filter((scope) => allowedScopes.includes(scope));
}

The docs accurately describe the library. The mismatch is in the hosted service. The challenge header matches insufficientScope() in workers-oauth-provider, but refresh-scope handling and token validation are different. Do not assume that an OSS library and a hosted service with the same name behave identically.

I also found two related details: refreshes are serialized, and overlapping requests return 429 temporarily_unavailable; and the refresh_token rotates on every refresh.

I wrote a conclusion without having measured it

At first, I sent the three refresh cases back to back. The second and later requests failed with 429, so the requests that were supposed to test the main point never ran. Yet the script printed “scope was not broadened.” An empty diff did not mean that was the service's behavior; the request had not reached the relevant code.

I retracted the result and reran the tests with delays. I changed the script to treat 429 as “not measured yet” and retry with exponential backoff. Do not mistake a conclusion printed by a script for an observation.

11. The 2026-07-28 protocol has no `initialize`

This was the first implementation snag. I sent initialize and got a 400 response:

-32020 the request headers and body disagree: an initialize request
       (legacy handshake) was sent with a modern MCP-Protocol-Version header
-32602 the MCP-Protocol-Version header names protocol revision 2026-07-28,
       but the request is missing the required per-request envelope key(s): _meta
-32020 the body names method tools/list but the required Mcp-Method header is absent

The 2026-07-28 protocol is stateless and has no initialize handshake. Instead, every request carries this in params._meta:

{
  "_meta": {
    "io.modelcontextprotocol/protocolVersion": "2026-07-28",
    "io.modelcontextprotocol/clientCapabilities": {},
    "io.modelcontextprotocol/clientInfo": { "name": "…", "version": "…" }
  }
}

It also repeats the request body information in headers: Mcp-Method: tools/call and Mcp-Name: <tool name>. That lets an intermediary route or rate-limit requests without opening the body—a useful design for a company that operates a CDN. The Claude Code binary does the same thing.

The legacy initialize still works if you omit the MCP-Protocol-Version header. I confirmed both 2025-11-25 and 2026-07-28 return 200 with the same token.

Aside: a 401/403 mix-up
This is not directly related to step-up, so I will keep it short. A randomly generated 43-character string that had never been issued returned 403 insufficient_scope instead of 401 invalid_token. Binary search narrowed the boundary to exactly 40 characters: strings of 40 or more [A-Za-z0-9_-] characters got a 403; 39 or fewer characters, or strings containing ., :, or spaces, got a 401.

Since 403 insufficient_scope triggers step-up in MCP, I wondered whether an expired client might be prompted to request more permissions. It did not. I tested three realistic cases, and all returned 401:

State a real client might have Result

A real, revoked token 401 invalid_token

A valid token for another resource 401 invalid_token

A malformed string / 39 characters or fewer 401 invalid_token

Only a deliberately constructed, never-issued string returned 403. It is an implementation flaw, but it has no practical impact.

I also tested revocation granularity. Revoking an access token leaves the refresh token alive. Only revoking the refresh token results in invalid_grant "Grant not found".

State a real client might have	Result
A real, revoked token	401 `invalid_token`
A valid token for another resource	401 `invalid_token`
A malformed string / 39 characters or fewer	401 `invalid_token`

12. So what actually changes?

There are three differences. Everything else is still OAuth:

Who notices that permission is missing? It moves from the application to the server.
Is there a way to communicate it? It moves from none (because the app already knows) to WWW-Authenticate.
Who remembers previously granted scopes? It moves from the authorization server to the client.

Reauthorization itself is the authorization-code flow in both cases. Step-up does not replace OAuth; it is an entry point back into OAuth.

Testing also made it clearer why MCP needs this. In a traditional web app, developers know which scopes each feature needs. With MCP, the AI selects a tool based on the user's request, so the client may not know in advance. With a tool like execute() that can call an arbitrary API internally, the needed permission may not be known until the tool runs. The server is the only component that can notice, so it needs a way to communicate that fact.

Looking at the implementation, the responsibility that the spec assigns to one side was held by both sides in practice: the client builds a union, and the server returns one too. That is a sensible transition strategy. Older clients do not break.

The remaining issue is in §9. When an operation does not return a 403, the AI cannot tell that permission is missing. This is less a Cloudflare-specific flaw than a mismatch between permission-filtered lists and AI agents. APIs have returned empty lists for a long time; a human might guess that their permissions hide the results. AI does not infer that. It reports that nothing exists.

As an MCP server author, I took away one thing: do not silently return an empty list when permissions are missing. Return a 403 challenge, and the client can ask the user. The specification provides the path. Whether an operation uses it is up to the server implementation.

13. Update: I reported it, and it was fixed that day (2026-10-21)

After publishing the article, I reported the §9 issue to cloudflare/mcp as Issue #302, titled “A list filtered down to nothing by permissions never raises a scope challenge.”

Ten minutes later, I opened PR #304. Two minutes after that, Cloudflare opened PR #305.

Time (UTC)	Event
14:41	Issue #302
14:51	PR #304 (mine)
14:53	PR #305 (Cloudflare)
22:11	#305 merged

This was not a retrospective rewrite: both PRs were opened almost simultaneously. #305 was the one that merged, with this note:

Fixes #302, building on @tanahiro2010's report and branch.

The merged commit includes my name in Co-authored-by. I expected the report might be accepted and fixed, but I did not expect the fix to build on my branch and credit me as a co-author.

One goal accomplished: becoming a contributor to some Cloudflare repository while still a student. Well, I guess maintainer is next…

What changed

Lists empty because of missing permissions are now treated as refusals. GET /zones, which previously returned 200 with an empty list, now returns 403 and a WWW-Authenticate challenge. The same applies to execute, endpoint tools, and forge tools.

Of the three failure modes in the article's original table, the second now matches the first:

Operation	At publication	After #305
R2 / KV / D1	403 + challenge	Unchanged
List zones / Workers scripts	200 + empty list	403 + challenge
`/user/tokens`	403 in result text	Unchanged

A useful implementation detail

One thing I liked in the implementation is that it does not treat every empty list as suspicious.

authorize() in src/api-permissions.ts returns one of granted, missing, unreachable, direct, or unlisted. refusalFor() in src/api-refusals.ts converts an empty list into a refusal only when the result is missing. It does not challenge a list that contains even one item.

That means accounts that really have zero items are not caught up in this. The challenge applies only when the connection has none of the scopes accepted by that endpoint. If the account really is empty, the user is asked about scopes once and the flow ends.

The refusal message is also careful: it does not claim that Cloudflare returned a 403. It says that the server returned 200 and an empty list, then adds the challenge without misrepresenting the response.

The naming mismatch I mentioned in §6 was fixed too. Aliases now map values such as Zone Zone Read from x-api-token-group to their catalog scope names. Without that mapping, the refusal could incorrectly tell users that no OAuth scope covers the endpoint. That is what GET /zones reported before my issue.

The tests record and classify responses for 549 endpoints. tests/filtered-lists.test.ts adds 292 lines, and the test fails against main before the fix.

Where this article stands

I am keeping §§9 and 12 as a record of what I observed at publication. If you call mcp.cloudflare.com now, the zone list no longer returns an empty array.

The broader conclusion still holds: whether an MCP server silently returns an empty list or a 403 challenge when permission is missing is the server author's decision. The spec provides the path, but the implementation decides whether to connect it. Cloudflare has now connected it.

References

Cloudflare API MCP server now supports step-up authorization — The announcement that started this investigation. Add /index.md to read it as Markdown.
Choose OAuth scopes for Wrangler and the Cloudflare API MCP server — Optional scopes and Edit Permissions on the consent screen.
MCP Specification 2026-07-28 — Authorization — Step-Up Authorization Flow and Scope Challenge Handling.
MCP Specification 2025-11-25 — Authorization — The version with three server-side union strategies.
Issue #2349 — Why responsibility moved to clients; the issue body explains the three arguments.
typescript-sdk#1582 — Reproduction of the infinite reauthorization loop.
cloudflare/workers-oauth-provider — insufficientScope() and the two scopes_supported lists.
Google — Using OAuth 2.0 for Web Server Applications — include_granted_scopes and combined authorization.
RFC 6750 §3.1 — Definition of insufficient_scope.
RFC 9470 — Step-up Authentication, which is a different concept.
cloudflare/mcp Issue #302 — The report from §9, filed after publication.
cloudflare/mcp PR #305 — The merged fix; authorize() and refusalFor() are worth a look.

I Migrated a Cloudflare Agents Workspace and Measured Everything: What Changes When the Storage Format Changes?

Hirohisa Tanaka — Thu, 22 Oct 2026 01:07:27 +0000

The difference was not the table names.

TL;DR

On October 20, 2026, Cloudflare Agents switched its Workspace implementation from @cloudflare/shell to @cloudflare/computer. The change is not just a new API name. It changes how files are stored. The old implementation stored one row per path, with the file contents base64-encoded in that same row. The new one separates inodes and chunks, storing content-addressed blobs in 512 KiB pieces.

I ran the old and new implementations in the same Durable Object and compared the data before and after migration.

The tables are different, so old files are invisible after switching without migration. They are still there, though.
Storing a whole file in one row changes the size limit and performance. The old implementation hit a limit at about 6 MiB, and its 1 MB read/write cycle was 13.5 times slower.
The schema is versioned, so it migrates forward automatically but cannot go backward.

Aspect	Old `@cloudflare/shell`	New `@cloudflare/computer`
Tables	`cf_workspace_<namespace>`	`vfs_` / `_vfs_`
Representation of one file	One row (`path TEXT PRIMARY KEY`)	Inode + 512 KiB chunks
Where content lives	Base64 in the same row's `content` column	Blob addressed by SHA-256
Observed file-size limit	About 6 MiB without R2	No single-row limit; content is chunked
1 MB write + read	87.25 ms	6.45 ms
Same content at two paths	Stored twice	Both paths share one blob row
Reopen with old implementation	Works	Fails with `EIO`

Test code: GitHub repository

Here is the main point upfront.

The old and new implementations differ in storage format, not API. Once you understand that, the reason files disappear after switching without a migration, why the file-size limit changes, why the new implementation is faster, and why you cannot switch back all follow from the same underlying change. The migration guide says to copy files manually because the tables differ. The deeper difference is their structure, not their names.

This article expands on my talk about migrating a Cloudflare Agents Workspace with measurements I could not fit into the presentation. It is for people using Cloudflare Agents who are preparing to move to @cloudflare/computer.

1. The announcement

On October 20, 2026, Cloudflare posted this changelog:

Think and Agent Skills now use the workspace from @cloudflare/computer as well as the filesystem tools.
@cloudflare/shell is deprecated, and so is Think's createExecuteTool. These will no longer be developed nor supported from today onwards.

On the same day, Cloudflare published @cloudflare/think@0.21.0, @cloudflare/computer@0.6.0, and agents@0.29.0. @cloudflare/shell also received version 0.5.0 that day to announce its deprecation. npm's deprecated flag applies retroactively to earlier versions too, so 0.4.3 shows the same warning.

The migration guide itself had landed earlier, in PR #2564 on October 14. It did not arrive at the same time as the announcement.

The Changelog also says:

This is a breaking change. @cloudflare/computer stores files in different tables from @cloudflare/shell, and there is no automatic data migration between workspace formats.

“Different tables.” That is where I started. Let's see how different they are.

2. The old Workspace stored one file per row

A Workspace is where an agent stores its files. A model interacts with them through read, write, edit, and ls; the files themselves live in Durable Object SQLite.

The old @cloudflare/shell schema is included in the migration guide:

CREATE TABLE cf_workspace_default (
  path             TEXT PRIMARY KEY,
  parent_path      TEXT NOT NULL,
  name             TEXT NOT NULL,
  type             TEXT NOT NULL CHECK(type IN ('file','directory','symlink')),
  mime_type        TEXT NOT NULL DEFAULT 'text/plain',
  size             INTEGER NOT NULL DEFAULT 0,
  storage_backend  TEXT NOT NULL DEFAULT 'inline' CHECK(storage_backend IN ('inline','r2')),
  r2_key           TEXT,
  target           TEXT,
  content_encoding TEXT NOT NULL DEFAULT 'utf8',
  content          TEXT,
  created_at       INTEGER NOT NULL DEFAULT (unixepoch()),
  modified_at      INTEGER NOT NULL DEFAULT (unixepoch())
);

It is straightforward: the path is the primary key, and the metadata and content live in the same row. The content column holds file contents, base64-encoded for binary files.

Large files are handled separately. The default threshold is 1,500,000 bytes. Files above that threshold are moved to R2, leaving only an r2_key in the row. If no R2 bucket is provided, the implementation logs a warning and keeps the file inline:

if (size >= this.threshold && !r2)
  console.warn(`[Workspace] File ${path} is ${size} bytes but no R2 bucket was provided. Storing inline.`);

This “put everything in one row” design matters later.

3. The new Workspace separates inodes and chunks

The new @cloudflare/computer uses several tables:

Table	Stores
`vfs_dirents`	Parent inode + name → child inode
`vfs_nodes`	Inode metadata (type / mode / mtime / size / link_target)
`vfs_chunks`	Inode + chunk index → blob SHA-256
`vfs_blobs`	SHA-256 → size and last-reference time
`vfs_blob_bytes`	SHA-256 → actual bytes
`vfs_meta`	`schema_version` and revision counter

Path resolution walks vfs_dirents from the root (inode = 1). File contents are split into 512 KiB chunks, each stored in vfs_blob_bytes as a blob keyed by SHA-256:

const CHUNK_SIZE = 524288;

The tables start with vfs_ or _vfs_, so they do not collide with cf_workspace_*. Both formats can coexist during migration.

From here, I measured what follows from the structural difference.

4. Consequence #1: switching does not make old files visible

I put both implementations on the same Durable Object. Splitting them across two DO namespaces would not test migration on the same storage. I switched between them inside one class.

I wrote 13 items with the old implementation, initialized the new one, and tried reading them:

Read through old Workspace before switch → {found: true, length: 23}
Initialize new Workspace
Read /workspace/notes.md through new     → ENOENT no such file
Read /notes.md through new               → ENOENT no such file
New-side tree                            → [{path: "/workspace", type: "dir"}]

The new implementation could not see the files.

If I stopped here, the article would say “the data is gone.” That would be quick—and wrong.

Add two controls

“Not visible through the new implementation” does not tell us whether the original write failed. In the same run, I verified that the old Workspace could still read the file both before and after switching:

Read through old before switch        → {found: true, length: 23}
Read through old after switch         → {found: true, length: 23}
Rows in cf_workspace_default          → 14 (same as before)

The old implementation could still read the file after the switch. The row count had not changed either.

The data was not gone. The new implementation was looking somewhere else. A table listing showed both formats coexisting:

cf_workspace_default
computer_execution_runtime
sqlite_sequence
vfs_blob_bytes   vfs_blobs    vfs_changes   vfs_chunks
vfs_dirents      vfs_manifests  vfs_meta    vfs_nodes
_vfs_fetch_cursor  _vfs_mounts  _vfs_push_cursor
_vfs_sync_operations  _vfs_sync_skips  _vfs_watermark

I also learned that all vfs_* tables are created as soon as you call new Workspace(). They do not wait for the first filesystem operation. The schema_version was 10.

5. Consequence #2: the size limit changes when everything fits in one row

The old implementation base64-encodes file contents and puts them in one cell. A 4 MB file becomes 5,592,408 base64 characters.

Meanwhile, the Durable Objects Limits page says:

Item	Documented limit
Maximum string, `BLOB`, or table row size	2 MB
KV key size	Key and value combined cannot exceed 2 MB

A 4 MB file should not fit in the old Shell. I predicted that while designing the benchmark and prepared files of 1 KB, 100 KB, 1 MB, and 4 MB.

They all worked.

My prediction was wrong.

4 MB → storage_backend=inline, content_encoding=base64,
       content_len=5,592,408 → read-back SHA-256 matches
8 MB → Error: string or blob too big: SQLITE_TOOBIG

I got the same result in local Miniflare and a deployed production Durable Object.

Measurement: where is the actual limit?

Stepping through the library would only reveal its implementation constant, not the underlying limit, so I called ctx.storage.sql and ctx.storage.kv directly to find the boundary. Each probe used a new Durable Object.

Largest accepted  8,388,627 bytes
Smallest rejected 8,388,628 bytes

8 MiB is 8,388,608 bytes. TEXT, BLOB, and a KV value all failed at the same boundary.

That is four times the documented 2 MB. I repeated probes around the boundary on a new Durable Object and got the same result. I reported it in cloudflare-docs#34502. Since I could not rule out 2 MB being the guaranteed limit and 8 MiB merely an implementation allowance, I did not open a PR asserting a new limit; I attached a reference branch instead.

Why does the old implementation stop at 6 MiB?

The old Shell hit its own boundary below the raw SQL limit:

Largest file accepted by shell.writeFileBytes  6,291,408 bytes (8,388,544 base64 chars)
Smallest rejected                             6,291,409 bytes (8,388,548 base64 chars)

Base64 expands the content by about 4/3, so that works out to roughly 6 MiB of file data.

I could not explain why the Shell fails earlier than raw SQL at 8,388,627 bytes. I reproduced its DDL, indexes, INSERT statement, ON CONFLICT DO UPDATE clause, and base64 string, then ran them against the same Durable Object. Raw SQL accepted the value. I also suspected that UPSERT might duplicate the value through excluded, but an UPSERT against an existing row accepted the same size.

The stack trace points to the Shell's INSERT:

Error: string or blob too big: SQLITE_TOOBIG
  at Object.run (index.js:367:17)
  at Workspace.writeFileBytes (index.js:652:22)

I stopped there. For practical purposes, remember that “without R2, the old Shell's file-size limit is about 6 MiB.”

The new Computer splits content into 512 KiB chunks, so this particular wall is gone. Files of 8 MB, 16 MB, and 32 MB all worked. Chunking may look like a performance design, but it also changes the size limit.

6. Consequence #3: base64 conversion on every operation is slower

I hit an oddity here: Date.now() does not advance inside a Worker. In production, even a 4 MB write was recorded as 0ms. It advanced in local Miniflare, so at first I thought I was misreading the production logs.

I measured from outside instead. I sent one request that repeated the operation 60 times and a control request that did nothing, then divided the difference by 60. The table shows the median of seven runs:

Size	Old Shell	New Computer
1 KB	1.58 ms	-0.75 ms
100 KB	4.92 ms	0.80 ms
1 MB	87.25 ms	6.45 ms

I cannot draw conclusions from the 1 KB and 100 KB results. As the negative value shows, the differences are buried in HTTP round-trip variance.

At 1 MB, the gap was clear: 13.5×. The old Shell base64-encodes a 1 MB file into one row on every write and decodes it on every read, adding overhead. My measurement includes the write and the read together, so I cannot say which one is slower on its own.

7. Consequence #4: content addressing enables deduplication

The new implementation uses the blob's SHA-256 as its primary key. The same bytes can be shared by files anywhere in the tree.

I wrote the same 512 KiB of content to two paths and counted rows in vfs_blobs:

Initial blob count                 → 0
Write identical content to path 1  → 1
Write identical content to path 2  → 1  (no increase)
Control: write different content  → 2  (increases)

Without the control, I could not distinguish deduplication from an implementation that never added a blob at all. The different byte sequence confirmed that a second row is created when the content differs.

The old implementation stores content per path, so putting the same file in two places uses storage twice.

8. Consequence #5: there is nowhere to put some metadata

The old FileInfo has mimeType, createdAt, and updatedAt. The new WorkspaceStatResult has only these fields:

{ name, inode, mode, mtime, size, isFile, isDirectory, isSymbolicLink }

There is no API in workspace.fs to read or write MIME types. There is only one timestamp, mtime.

The migration guide also says this metadata is not retained:

Things the copy does not keep:

created_at and modified_at. Computer stamps the time of the copy.

mime_type. Computer does not store a MIME type per file.

In my measurements, every migrated file's mtime was the time the copy ran. It is not just that the data is “not retained”; the new schema has nowhere to store it.

9. Consequence #6: you can move forward, but not backward

The new implementation versions its schema. Its initialization code looks like this:

const onDiskVersion = db.one("SELECT v FROM vfs_meta WHERE k = ?", "schema_version")?.v ?? 0;
if (onDiskVersion > 10) throw createWorkspaceError("EIO", `Unsupported workspace filesystem schema version ${onDiskVersion}`);
if (onDiskVersion > 0 && onDiskVersion < 10) runMigrations(db, onDiskVersion, 10);

Migrations run forward automatically. There are nine registered migrations, from v1 to v10.

There is no migration backward.

Rather than deploying an old version, I changed the on-disk schema_version to 11 to simulate a database newer than the binary, then ran the same initialization path:

Current schema_version                 → 10
Control: reconstruct with same version → {read: "hello"}
Set schema_version to 11
Open again with older binary            → EIO Unsupported workspace filesystem schema version 11
Set schema_version back to 10
Can it open now?                        → {read: "hello"}

What I measured is that the binary cannot open a database whose on-disk schema_version is newer than the version it supports. This means “you cannot roll back” only if a new release raises the schema version. It has already been raised nine times, so it is reasonable to expect that it could happen again.

Neither the migration guide nor the Changelog mentions this. There is one sentence in the implementation document 03_filesystem_schema.md:

Open() refuses to run if the binary is older than the on-disk schema_version.

The old data remains, so if migration fails you can still read from the old tables. The inability to roll back is the less recoverable part.

10. Running the migration guide's script

Now that I understood the structural difference, I ran the migration.

The guide provides a copy function named copyShellWorkspace(). It walks the old Workspace with glob("/**") and writes the files through the new fs API. The destination is under /workspace, which Think also uses as its working directory.

I ran the script without changing it. My test data included UTF-8 Japanese text, TypeScript in a nested directory, JSON for exact-content comparison, 64 KB of binary data generated with a deterministic pseudorandom sequence, an empty directory, and four symlinks covering relative, absolute, and root-escaping targets.

comparison → {
  total: 13, missing: [], typeChanged: [],
  contentMismatch: [], extra: []
}

All 13 items existed after migration, their types had not changed, and the 64 KB binary's SHA-256 matched. The empty directory remained too. I got the same result in local wrangler dev and in a deployed production environment.

I also verified that the hash comparison could actually detect a mismatch. I changed one bit in a byte sequence and confirmed that it produced a different hash: af2ba40f… versus 73734ea1…. A comparison that cannot detect a mismatch does not prove that two files match.

I checked one assumption the script relies on as well. A comment says, “glob returns rows ordered by path, so parents come before children.” If that were false, writeFile could run before mkdir. In my tests, results were sorted lexicographically, so each parent appeared before its children.

Symlinks need one extra check

When I followed each link individually, one of them failed:

Link	Target in Shell	Target after migration	Can follow it?
`/links/rel.md`	`../notes.md`	`/workspace/notes.md`	Yes
`/links/abs.md`	`/notes.md`	`/workspace/notes.md`	Yes
`/links/dotdot.md`	`/src/../notes.md`	`/workspace/src/../notes.md`	Yes
`/links/esc.md`	`/../notes.md`	`/workspace/../notes.md`	ENOENT

/workspace/../notes.md resolves to /notes.md, which is outside the migration destination /workspace.

The cause is in the script's resolveTarget():

// Shell resolves a relative target against the link's directory and never
// goes above `/`.
function resolveTarget(link: string, target: string): string {
  if (target.startsWith("/")) return target;   // Absolute paths pass through
  const parts = link.split("/").slice(1, -1);
  for (const part of target.split("/")) {
    if (part === "..") parts.pop();
    else if (part !== "" && part !== ".") parts.push(part);
  }
  return `/${parts.join("/")}`;
}

The @cloudflare/shell implementation (resolveSymlink) also sends absolute paths through normalizePath. normalizePath stops .. at the root, so /../notes.md becomes /notes.md in Shell. The migration script passes the path through unchanged. When it prefixes /workspace, the target escapes that directory.

The conditions are narrow. Relative paths all migrate correctly. Absolute paths containing ., //, or .. that does not go above the root also work. The only failure is an absolute path containing .. that goes above the root.

The script does not report an error. symlink() saves the target without validating it, and following it stops at the root rather than throwing. This is like a legal dangling link on POSIX. The copy completes successfully.

A path/type/hash comparison will not catch this. The link exists, so it is not missing. Its type is still symlink, so the type matches. It has no file content, so it is not included in the hash comparison. My own comparison script reported missing: [], contentMismatch: []. To catch this, you have to follow and read the link:

await to.fs.readFile(linkPath, "utf8");   // ENOENT if the target cannot be followed

A second issue is that the migration is not safe to rerun:

First migration  → ok
Second migration → EEXIST path exists: /workspace/links/abs.md

mkdir({ recursive: true }) silently succeeds for an existing directory. writeFile overwrites unless exclusive is specified. symlink(target, path) has no equivalent of a force option; if the path already exists, it always throws EEXIST. That matches Node's fs.symlink behavior and is not a library bug.

The guide's onStart example sets a flag after copying completes. If the copy fails partway through, the flag is never set and the next startup fails again on the same link. Remove the link before recreating it:

const link = at(entry.path);
if (await to.fs.readlink(link).then(() => true, () => false)) {
  await to.fs.rm(link);
}
await to.fs.symlink(at(target), link);

I reported these two issues in cloudflare/agents#2645. Before filing, I checked for duplicates and found that both had been raised in earlier reviews. One did not survive a PR replacement; the other had been marked resolved based on the incorrect assumption that absolute paths were already rebased. Checking first meant I did not present either as a new discovery.

If your Workspace has no symlinks, you will not hit this part.

11. Persistence survives hibernation

The storage format changed, but the files still live in Durable Object SQLite. I checked whether they survive restarts.

“Readable from another request” is not enough evidence. The same instance might still be in memory and return the file from there. I generated a crypto.randomUUID() in the constructor and included it in the response. If that value changes, the Durable Object is a new incarnation.

                     bootId                                  Read
1. Write             1cadfbdd-7595-4879-94c1-43abca4688c0   ok
2. Read immediately  1cadfbdd-7595-4879-94c1-43abca4688c0   ok   (same)
3. After 15 seconds  e4f5f2ab-3d7d-4389-8e2d-ee32fdd97b02   ok   (changed)
4. After 150 seconds c602f7f1-c9f6-465e-9b36-0c3259706d64   ok   (changed again)

Reads 3 and 4 came from different incarnations. The file content included the old bootId from when it was written, showing it was the same data.

I decided which fields to record before running the test: a case number for writing back the verdict, bootId to show whether a restart happened, env to distinguish local from production, sha256 and size to identify the file, the operation's elapsed time, and ok and error fields that hold results instead of throwing exceptions.

This control proved useful. After redeploying, my first immediate read succeeded, but the bootId was unchanged. The DO was still in memory and running the old code; it had not restarted. Without the control, I might have concluded that the file persisted across a restart. I waited 15 seconds and tried again, then confirmed that the bootId changed and the file was still readable.

How long until hibernation?

I varied the wait time and checked bootId. The zero-second wait was the control:

Wait (s)  Restarted  Read
      0   No         ok   (control)
      3   No         ok
      6   No         ok
      9   No         ok
     11   Yes        ok
     13   Yes        ok
     15   Yes        ok

The boundary is between 9 and 11 seconds, matching the documentation's “hibernate after 10 seconds of inactivity.”

12. Before you migrate

Count your symlinks. Run glob("/**") and count entries with type === "symlink". If there are none, the official script should work as-is.
If you have links, follow and read them after migration. Path/type/hash comparisons will not catch the issue.
Check for files larger than 6 MiB. If the old implementation stored them in R2, pass the same r2 bucket and name during migration.
Deploy assuming you cannot roll back. Once the new schema has been written, an older @cloudflare/computer cannot open that Durable Object.
Do not delete the old data immediately. The old tables remain, so wait to DROP TABLE until your comparison is done.

The dependency arrangement changes too. In @cloudflare/think@0.20.2, @cloudflare/shell was a direct dependency; you did not install it yourself. In 0.21.0, @cloudflare/computer is a peer dependency. The mechanism behind “I upgraded and my Workspace is empty” is right there.

13. Conclusion

The storage format changed, and the rest followed from it:

Different tables → files are invisible after switching without a migration, but the old tables remain and the old Workspace can still read them.
One row versus chunks → the old implementation hits a limit at about 6 MiB; the new one accepts files of 32 MB.
Base64 conversion on every operation → a 13.5× difference in the 1 MB read/write test.
Content-addressed blobs → the same content at two paths takes one blob row.
Fewer metadata columns → there is nowhere to store mime_type or created_at.
A versioned schema → it migrates forward automatically and cannot be opened by an older implementation after the version changes.

The migration guide says to copy files manually because the tables differ. The difference is not just the table names; it is the structure. Understanding that structure tells you what to verify before you migrate.

I also found two mismatches with the documentation. The Durable Object SQLite value limit I tested was 8 MiB, not 2 MB, and the user-facing docs do not mention that an older implementation cannot open a Durable Object after its schema has been upgraded.

The most surprising result was that a 4 MB file worked. I had predicted the result from the official limit and got it wrong. Because I had trusted the documented number, I no longer trusted my other predictions once it failed. I ended up measuring both the size limit and performance myself. That took more time than the migration itself.

References

Think agents now use a @cloudflare/computer workspace — The announcement, the lack of automatic migration, and deprecation of createExecuteTool.
Migrating from @cloudflare/shell to @cloudflare/computer — Both schemas and the copy script discussed in §10.
cloudflare/computer docs/03_filesystem_schema.md — All vfs_* table definitions, chunk size, and schema version behavior.
Durable Objects — Limits — The documented 2 MB row-size limit tested in §5.
Durable Objects — Lifecycle — Sources for the 10-second hibernation and 70–140-second eviction behavior.
cloudflare/computer#217 / #219 — Acknowledgment that writing to R2 and namespaces are not supported yet.
cloudflare/agents#2645 — Report about the symlink migration script in §10.

Investigating the Return of the PHP2Shell Nightmare

Hirohisa Tanaka — Thu, 22 Oct 2026 00:56:06 +0000

The public PoC claiming “RCE via a PHP core UAF” did not work in my lab. After reading the official patches, the actual causes turned out to be state corruption during OOM handling and state left behind across requests—not a zval UAF within a single request.

What this article concludes

I built a local Docker lab to investigate the PHP vulnerability making headlines as “php2shell,” compared the public PoC with PHP source code, and then read the patch diffs published with the official releases. The result: the “PHP core UAF” described by the public PoC did not reproduce, and the official root causes were different. However, a chain combining the session.upload_progress write primitive with an application-level LFI did work.

On October 21, 2026, PHP released 8.5.12, 8.4.27, 8.3.36, and 8.2.35. CVE-2026-109618 is “OOM corruption,” and CVE-2026-109619 is “stale global state across requests.” Both have a CVSS v4.0 score of 9.2, and the official advisories explicitly call them RCE vulnerabilities.
The public PoCs for 618 and 619 did not reproduce a UAF or RCE in PHP 8.4.4 and 8.5.4 ASAN builds, PHP 5.6.40, with ASLR disabled, or with a poisoned call address.
The patches do not primarily fix the alleged “zval corruption on the second update” in ext/session. They redesign the OOM bailout path, initialize session state before RINIT, and reset state left behind by earlier requests. The public PoC identified the wrong root cause.
A chain using session.upload_progress and an application-level LFI did reproduce. It worked not only with cleanup=0, but also in a 3/3 race with the default cleanup=1; RCE through an uploaded temporary file also remained with enabled=0. The official advisory also identifies Session Upload Progress as a confirmed consumer for 619.
So the accurate conclusion is neither “the PHP core gives you universal RCE” nor “PHP2Shell is a hoax.” The core CVEs are real, and upgrading is the only complete fix for them. But an application-level LFI chain can remain after upgrading. These are two separate layers.

Test	Result
Public PoCs 618/619 (8.4.4 ASAN)	Not reproduced
Public PoCs 618/619 (8.5.4 ASAN / 5.6.40)	Not reproduced
LFI with `cleanup=0`	`uid=33(www-data)`
Race with default `cleanup=1`	`uid=33(www-data)` in 3/3 attempts
Temporary-file include with `enabled=0`	`uid=33(www-data)`
`use_strict_mode=1` with `Set-Cookie` follow-up	`uid=33(www-data)`
mod_php (Apache)	`uid=33(www-data)`

The test code and raw logs are available in the repository.

Here is the most important point upfront:

“The public PoC does not work” and “the vulnerability does not exist” are different claims. The public PoC may help explain source locations, but it does not prove RCE. On the other hand, the session.upload_progress primitive is real, and combining it with an application-level LFI can reach code execution without authentication. Do not assert the core root cause until you have read the official patch diffs. That is the minimum standard for avoiding being misled by information circulating during an embargo.

This article expands my PHP2SHELL investigation with source reading and experiment logs that I could not cover in my talk. It is for people who develop or operate PHP applications and want to distinguish vulnerability claims from observed behavior.

1. What happened

On October 20, 2026, PHP’s official website posted a short notice titled “Upcoming Critical PHP Security Release.” It said that fixes for two critical vulnerabilities would be released the following day, October 21, at 14:00 UTC (23:00 JST). Both had a CVSS v4.0 score of 9.2. Details, affected versions, and fixed versions would be published at release time.

The notice was only about four lines long. But information leaked before the notice was followed by the release. Fragments such as possible CVE numbers, session.upload_progress, impact on PHP 5.4 and later, and CVSS 10.0 circulated on social media and Hacker News. Researchers and security companies posted that the vulnerabilities were RCE and that they had reproduced them. None of the official PHP notice mentioned a CVE number, “RCE,” or “Session Upload Progress.”

That abnormal order is the central theme here. Leaked information and secondhand claims spread before the official facts were confirmed. Some of those claims later raised questions about whether the public PoC was reproducible.

Criticizing the situation would not tell me what was actually happening, so I built a local Docker lab. I compiled PHP with ASAN, ran the public PoC, read the PHP source, and checked which claims were supported by evidence.

I wrote the first draft based only on the advance notice. The official release was published by 22:45 JST on October 21, and confirmed the CVE numbers, causes, affected versions, and fixed versions. To keep the facts available at announcement time separate from what became known after release, I have kept this section as an account of what was known from the notice and summarized the release results in §10.

2. What the official notice did—and did not—confirm

At the time of the notice, the official source confirmed five things:

A security release was scheduled for October 21, 2026, at 14:00 UTC (23:00 JST).
There were two critical vulnerabilities.
Both had a CVSS v4.0 score of 9.2.
Details, affected versions, and fixed versions would be published with the release.
The release might be moved earlier if details became public or active exploitation was observed.

The official notice did not say:

The CVE numbers were CVE-2026-109618 and CVE-2026-109619.
The issues were classified as RCE.
session.upload_progress was involved.
Which versions were affected. “PHP 5.4 and later” was a leak claim. After release, the official fixes covered 8.2 and later; source backports were also provided for 7.4, 8.0, and 8.1.
Which version numbers would contain the fixes. 8.5.12, 8.4.27, 8.3.36, and 8.2.35 were unverified guesses at the time. All four were later confirmed.

Item	Official notice	Researchers / leaks	My lab
Two issues / CVSS 9.2 / date	Confirmed	Consistent	—
CVE numbers	Not listed	Claimed	—
RCE	Not listed	Claimed	Core UAF not reproduced
Session Upload Progress	Not listed	Claimed	Primitive confirmed
PHP 5.4+	Not listed	Leak claim	Primitive confirmed on 5.6.40
Fixed versions	Not published	Guessed	Not tested yet

The October 21 release filled in every “not listed” and “not published” cell. The CVE numbers were real, the official advisories called the issues RCE, and all four guessed fixed versions were correct. I summarize the difference between the notice and the release in §10.

The disagreement over CVSS is especially illustrative. PHP’s official score was 9.2. Meanwhile, the CEO of watchTowr told the press, “Both of them are CVSS10.” This is not about deciding which score is right. It shows how a secondary claim of 10.0 can spread even while the official source says 9.2. That was the information environment around this incident.

3. What Session Upload Progress does

session.upload_progress is a PHP feature that writes file-upload progress into a session. If a multipart/form-data POST contains a field named PHP_SESSION_UPLOAD_PROGRESS, PHP writes progress data to $_SESSION["upload_progress_<value>"]. The progress data can include start_time, content_length, bytes_processed, done, and files[].

The important detail is that progress is written before the application script runs. PHP writes it while parsing the POST body, before the application’s authentication or input validation. The PHP engine does this even when the application does not use a progress display.

sequenceDiagram
    participant A as Attacker
    participant W as Web server
    participant P as PHP multipart parser
    participant S as ext/session
    participant App as Application
    A->>W: POST multipart (PHP_SESSION_UPLOAD_PROGRESS=...)
    W->>P: Request body
    P->>S: MULTIPART_EVENT_START / FORMDATA
    S->>S: progress->key = "upload_progress_" + value
    P->>S: FILE_START / FILE_DATA
    S->>S: Write to session file before app runs
    P->>App: Run script
    App->>App: session_start() exposes progress data

The defaults matter too: session.upload_progress.enabled is On, session.upload_progress.cleanup is On (progress is removed at the end of the request), and session.use_strict_mode is 0 (an attacker can specify a session ID). These defaults lead into why changing a single setting is not enough.

4. Reading php-src: two layers, a callback and a parser

Reading php-src shows that this feature has two layers:

The multipart parser itself in main/rfc1867.c.
The progress callback in ext/session/session.c.

main/rfc1867.c has a global function pointer named php_rfc1867_callback. The parser calls it for START, FORMDATA, FILE_START, FILE_DATA, FILE_END, and END events. During MINIT, ext/session registers php_session_rfc1867_callback by assigning it to php_rfc1867_callback, thereby hooking into the parser.

The callback starts with this early return:

if (!PS(rfc1867_enabled)) {
    return retval;
}

So setting session.upload_progress.enabled=0 stops only this callback. The parser in main/rfc1867.c still runs for multipart POST requests regardless of the setting.

The progress key is created during FORMDATA:

smart_str_appendl(&progress->key, PS(rfc1867_prefix).c, PS(rfc1867_prefix).len);
smart_str_appendl(&progress->key, *data->value, value_len);

After that, php_session_rfc1867_update() runs php_session_initialize() → zend_hash_update() → php_session_flush(), writing sess_<PHPSESSID> before the application script runs. The session ID is read early from the Cookie or GET parameter by php_session_rfc1867_early_find_sid(). With use_strict_mode=0, an attacker can choose an arbitrary ID.

flowchart TD
    A[multipart POST] --> B[main/rfc1867.c]
    B --> C{php_rfc1867_callback}
    C --> D[ext/session callback]
    D --> E{enabled?}
    E -- 0 --> F[Early return]
    E -- 1 --> G[Create progress->key]
    G --> H[Write session file]
    H --> I[Run application]
    B --> J[Parser continues running]

What we can conclude from this is the structure: the setting disables only the session callback. At the time of the first draft, it was not enough to say “therefore the second vulnerability is in the parser itself.” I give the answer in §10, but the official explanation was not “a UAF in the parser.”

5. Testing the public PoC’s “core UAF” claim

The public bundle Zer061/CVE-2026-109618 says that php_session_rfc1867_progress caches two zval * pointers, and that a second update() breaks the tree when the session file is decoded again and the old tree is freed by zval_ptr_dtor. It then claims that 149 t[] fields reclaim the freed memory, allowing a forged zend_fcall_info to call zend_call_function and reach system().

I built PHP 8.4.4 with ASAN and set USE_ZEND_ALLOC=0 so ASAN would also observe the Zend heap. I sent PoCs for 618 and 619 through PHP-FPM + nginx, and checked for ASAN reports, uid=, and worker crashes.

The result: I could not reproduce either the UAF or RCE. The progress-store path was reached: I could see bytes_processed=258 and files[0].bytes_processed=1. But there was no ASAN report, no uid=, and no worker crash. I got the same result with an ASAN build of PHP 8.5.4 (the build assumed by the public PoC’s DELTA_CALL), PHP 5.6.40, ASLR disabled, the actual address of zend_call_function, and the poisoned address 0x4141414141414141. A poisoned address not causing a crash is evidence that the stale pointer was not being used as a function pointer.

Instrumenting the source made the reason clearer:

post_bytes_processed points to a zval inside progress->data; progress itself holds a reference, so it remains alive during the update.
track_init / zend_hash_update free the copy decoded from the session.
The post read in update() happens before php_session_initialize(), while the free happens afterward.
The force=1 update at MULTIPART_EVENT_END skips the read entirely.
current_file_bytes_processed is also retained by the files[] array, and the FILE_END update changes an existing key.

The public bundle’s own VALIDATION.md says, “ASAN crash not observed locally.” The image attached to its tweet is a screenshot explaining the alleged mechanism, not execution evidence showing uid= or an ASAN report. The distributed tarball’s SHA-256 did not match the hash listed on its page (a29d… versus 0c254d…). The code was identical to the GitHub mirror, but anyone running it should pin a commit.

This does not prove that the CVE does not exist. It only means that the public PoC, at least as provided, did not reproduce RCE. In the first draft, I wrote, “The core root cause cannot be confirmed until the official patch diff is available.” The patch is now public, and §10 provides the answer. In short, the official root cause was different from the PoC’s story.

6. A chain that did work: multipart + LFI

The core UAF in the public PoC did not reproduce, but a chain combining the session.upload_progress primitive with an application-level LFI did.

The flow is:

The attacker chooses a PHPSESSID (use_strict_mode=0).
The attacker puts PHP code in PHP_SESSION_UPLOAD_PROGRESS.
Before the application runs, PHP serializes the value into sess_<PHPSESSID>.
An application LFI includes sess_<PHPSESSID>.
PHP code embedded in the key string (<?php ... ?>) executes.

sequenceDiagram
    participant A as Attacker
    participant P as PHP
    participant L as LFI app
    A->>P: PHPSESSID + PHP_SESSION_UPLOAD_PROGRESS
    P->>P: Write sess_<id> before app runs
    A->>L: ?file=/tmp/sess_<id>
    L->>L: include(sess_<id>)
    L-->>A: uid=33(www-data)

For the test, I used a local-only application that intentionally calls include($_GET['file']). The result was uid=33(www-data). The session file contained the PHP code embedded in the progress key:

upload_progress_<?php /* ... */ ?>|a:5:{s:10:"start_time";...}

The nginx access log also showed the following sequence:

"POST /index.php HTTP/1.1" 200 5
"GET /index.php?file=%2Ftmp%2Fsess_...&0=id HTTP/1.1" 200 414

This clarifies what people meant by “a few more vulnerabilities.” The central requirement is an application-level LFI or another sink that reads the session file. Other contributing factors can include SID fixation due to use_strict_mode=0, a race when cleanup=1, predictable session.save_path, and including an upload temporary file that remains available even when enabled=0.

This is not universal RCE from the PHP core alone. It requires an application-level sink. Mixing this with the alleged core UAF in the public PoC blurs two separate chains.

7. The default-setting race, `enabled=0`, strict mode, and mod_php

The default cleanup=1 does not make this safe. It removes progress at the end of a request, but progress remains during the upload. I sent the first chunk (6,000 bytes) to satisfy FPM’s FILLUNIT=5120, stalled for 1.5 seconds, and requested the LFI during that interval. The result was uid=33(www-data) in all 3 attempts.

enabled=0 stops progress from being written to the session. But multipart uploads continue, and $_FILES['f']['tmp_name'] is still created. If the application includes that file, another RCE path remains. Indeed, an include of the temporary file returned uid=33(www-data) even with enabled=0.

use_strict_mode=1 rejects an unknown SID chosen by an attacker. LFI with the chosen SID failed. However, the upload response’s Set-Cookie header contained a new SID. If the response can be read, the attacker can follow that SID. With my test’s --follow-cookie option, the result was uid=33(www-data).

The same chain also worked with mod_php (php:8.4.4-apache). This chain is independent of the SAPI.

Condition	Result
`cleanup=0`	`uid=33(www-data)`
Default `cleanup=1` + race	`uid=33(www-data)` in 3/3 attempts
`enabled=0` + temporary-file include	`uid=33(www-data)`
`use_strict_mode=1` + chosen SID	Failed
`use_strict_mode=1` + follow `Set-Cookie`	`uid=33(www-data)`
mod_php	`uid=33(www-data)`

8. How to read the shared impact assessment

I was also sent an impact assessment for a web application running PHP 5.6.40. I cannot disclose the application name or names of credential keys, so I have generalized the details.

The assessment did a good job of listing exposure conditions: PHP 5.6.40 is EOL and outside the scope of the official fixes; the session extension is installed; upload_progress is enabled by default; file_uploads is on; and all requests reach PHP. Together, these establish an attack surface. It was also practical to describe impact conditionally as the “blast radius if RCE is achieved.”

There are several caveats:

“enabled=Off means the vulnerable code path does not run” applies only to the session callback. The multipart parser and temporary files remain. My enabled=0 + temporary-file include test is a counterexample.
“This is RCE” was a researcher/leak claim at the time of the first draft, not yet confirmed by PHP. The October 21 release explicitly confirmed RCE. The assessment itself rated confidence as medium.
“PHP 5.6 is affected” was a leak claim. Official fixes cover 8.2 and later, with backports for 7.4, 8.0, and 8.1; PHP 5.6 remains outside the official scope and unconfirmed.
If an assessment does not mention LFI, it does not prove that RCE is achievable. The chain in my lab requires an application-level LFI.
Do not commit the assessment as-is to a public repository if it contains internal application names or secret-key names.

For an article, the accurate statement is that “the exposure conditions were present in a PHP 5.6.40 web application.” It would not be accurate to say “RCE was confirmed.” The assessment was about impact if RCE were achieved.

9. Mitigations and what they do—and do not—stop

Mitigations need to be evaluated by what they stop:

Mitigation	What it stops	What remains
`session.upload_progress.enabled=Off`	Progress writes to the session	Multipart uploads / temporary files
`session.upload_progress.cleanup=1`	Progress after request completion	Race during the upload
`session.use_strict_mode=1`	Attacker-chosen SID	Following the SID if `Set-Cookie` is readable
WAF / multipart restrictions	Some automated attacks	Legitimate uploads, other SAPIs, other sinks
Patch	The root causes identified by PHP	Application-level LFI / configuration issues
Least privilege / isolation	Limits impact after compromise	RCE itself

enabled=Off is the strongest mitigation for the session write primitive. However, multipart uploads and temporary files remain. If the application has a sink that includes uploaded files, that must be fixed separately.

cleanup=1 only removes progress after the request ends, so it does not prevent a race during upload. use_strict_mode=1 prevents the attacker from choosing a SID, but progress is still written. If the response’s Set-Cookie can be read, the SID can be followed.

That is why mitigations should be separated into three layers:

Patch — fix the core root causes.
Configuration — disable the primitive with settings such as enabled=Off.
Remove application sinks — eliminate LFI, includes of uploaded files, and code that reads session files.

Do not treat “set one option and you are done” as a complete response.

The official advisories also list concrete mitigations for the core issues: force memory_limit=-1 in administrator configuration (and prevent applications from overriding it), reduce post_max_size, use cgroup/container memory limits, set fatal_error_backtraces=0 on PHP 8.5, and set pm.max_requests=1 to prevent workers from being reused. The advisories explicitly say not to use RLIMIT_AS or RLIMIT_DATA, because they can cause mmap() failures and trigger the vulnerable path. These measures reduce attack paths, but PHP says there is no complete mitigation; upgrading is the only safe fix.

10. What the official release and patch diffs showed

The official release was already available at 22:45 JST, before the announced 23:00 JST time. I read it and checked my first-draft predictions one by one.

10.1 Facts confirmed by PHP

Item	Details
Fixed versions	PHP 8.5.12 / 8.4.27 / 8.3.36 / 8.2.35
CVE-2026-109618	RCE via OOM corruption (GHSA-w8hw-w9fx-j79w)
CVE-2026-109619	RCE via stale global state (GHSA-6wmf-4rv5-p3rp)
Severity	CVSS v4.0 9.2 for both
Scope	All PHP handling web requests: FPM, mod_php, php-cgi, FrankenPHP, LiteSpeed
Most dangerous setup	mod_php; a demonstrated attack works on an unauthenticated request before application code runs
8.1 and earlier	Outside official support. Minimal source backports only for 7.4 / 8.0 / 8.1
Mitigation	“There is no complete mitigation. Upgrading is the only safe fix.”

The official release’s explicit “RCE” classification superseded the first draft’s statement that PHP had not yet called it RCE. That statement was true only at announcement time. The CVE numbers and fixed versions also matched the leaked guesses.

10.2 The root causes differed from the public PoC’s explanation

The official GHSAs describe two causes.

CVE-2026-109618 (OOM corruption) abuses PHP’s use of longjmp() to bail out of processing when it runs out of memory. If an allocation fails while request memory is only partially initialized, PHP does not correctly account for the early bailout and leaves request memory in an invalid state. Request shutdown later reads or branches on that corrupted state. There are several ways for multipart parsing to hit memory_limit even while staying within post_max_size: multipart requests without Content-Length, unlimited headers inside parts, empty file controls not counted by max_file_uploads, and nested field names.

CVE-2026-109619 (stale global state) occurs when request-owned state remains in a worker global after the request memory has been freed. A fatal error or OOM interrupts processing before the corresponding reset runs. The request heap is released, but a worker global still points into that memory. If the next request reads the stale value before normal initialization, it triggers a use-after-free. PHP says both a producer (the operation that leaves the state behind) and a consumer (the operation that reads stale state) are required. In demonstrated cases, separate HTTP requests must be assigned to the same worker.

The official advisory names two consumers. One is INI diagnostics before request initialization (the path where .htaccess or FPM PHP_VALUE emits a warning or deprecation). The other is Session Upload Progress. It touches session/decoder state before normal session initialization. The sequence is that a previous request exits on a fatal error and leaves state behind, then the next upload reads it. session_start() is not needed, and the feature is enabled by default.

This is the decisive difference from the public PoC. The PoC said that a second update() within one request corrupts a zval in post_bytes_processed. The official root cause is state that was not reset across requests. It is not a UAF confined to one request.

10.3 Reading the patch diffs

The fix is commit 31c0ea7d7ff1d1fccb6492e52dab544011628065, titled “Avoid state corruption via bailout.” It names both GHSAs as fixes. I fetched the php-8.5.11 and php-8.5.12 tags and diffed the relevant files.

In ext/session/session.c, four things changed:

Call php_rinit_session_globals() at MULTIPART_EVENT_START, initializing session globals before RINIT.
Force unserialize/serialize during upload progress to use __PHP_Incomplete_Class. Since this happens before RINIT, it must not invoke autoload, __wakeup(), or __unserialize().
If php_session_initialize() returns FAILURE, do not set session_status to active; return instead.
Do not run the callback through request_parse_body() (PG(modules_activated)).

    case MULTIPART_EVENT_START: {
+       /* This runs before RINIT, so we need to clear these early */
+       php_rinit_session_globals();
        progress = ecalloc(1, sizeof(php_session_rfc1867_progress));

+    PS(in_rfc1867_update) = true;
+    if (php_session_initialize() == FAILURE || PS(session_status) != php_session_active) {
+        PS(in_rfc1867_update) = false;
+        return;
+    }

On the main/rfc1867.c side, the patch adds ZEND_HAS_OOM() checks and replaces allocations that could fail. The parser now keeps only Content-Disposition and Content-Type headers, narrowing the route for exhausting memory through part headers. In Zend/zend_alloc.c, the OOM longjmp() is removed and replaced with a deferred soft OOM; a second hard limit exits via _exit().

So, the public analysis was right that php_session_rfc1867_callback() was among the code being fixed. But the fix is not “prevent zval corruption on the second update.” It initializes session state that runs before RINIT and prevents user code from running pre-RINIT. Getting the function name right is not the same as getting the root-cause explanation right.

10.4 Why my lab did not reproduce the official issue

My initial lab followed the public PoC’s story: it tried only to trigger two updates in one request and corrupt a zval. The official 619 path uses a producer and consumer in separate requests, which must be assigned to the same worker. A single request cannot satisfy those conditions.

Also, the 619 producer requires a fatal error or OOM to skip a reset. My lab’s trigger exited normally, so it was not a producer. For 618, the key is that shutdown runs even when request startup fails in mod_php. The main lab used FPM, where the child exits if startup fails, so it does not follow the same path.

Therefore, “I could not reproduce it in my lab” does not prove the CVE does not exist or that PHP’s official root cause is wrong. I was testing different attack conditions. The same distinction applies to the public PoC: “this PoC does not prove RCE” and “the CVE is a hoax” are not the same statement. That boundary from my first draft turned out to be correct.

10.5 Which first-draft predictions were right?

First-draft statement	Result
Fixed versions would be 8.5.12 / 8.4.27 / 8.3.36 / 8.2.35	Correct
PHP had not yet called it RCE	True at announcement time; PHP explicitly called it RCE at release
Root cause was a zval UAF in `php_session_rfc1867_callback()`	Incorrect. PHP identified OOM and cross-request stale state
`session.upload_progress` was involved	Partly correct. It is a confirmed consumer for 619
Every PHP version from 5.4 onward was affected	Still unconfirmed. Official fixes cover 8.2+; backports for 7.4–8.1
`enabled=Off` is not a complete mitigation	Correct, though the reason also involves lifecycle paths beyond the multipart parser
The multipart + LFI chain is real	Correct. The application-level sink remains after the patch

10.6 The lab after patching

I built an ASAN version with PATCHED_VERSION=8.5.12 and reran the same trigger and LFI chain. The build was PHP 8.5.12, and the web SAPI was fpm-fcgi.

Test	Result on 8.5.12
`probe` (normal multipart)	`upload_progress=present`; file parsing OK
`trigger` (258 bytes)	`bytes_processed=258`, `done=true`
`poc618` / `poc619`	HTTP 200, no ASAN report, no `uid=`
LFI chain (8084)	`uid=33(www-data)`
FPM log	NOTICE messages for startup/shutdown only; no ASAN / crash

Two things can be concluded:

The session.upload_progress write primitive still works after the patch. This is a feature, not a vulnerability. The official patch fixes state that was not reset across requests, not the act of writing upload progress to a session. That is why probe and trigger return the same results as before.
The application-level LFI chain still works on 8.5.12. The official patch closes the core CVEs, but it does not remove an application sink that includes sess_<id> or an uploaded temporary file. That must be fixed separately.

To be precise, poc618 / poc619 not crashing on 8.5.12 does not prove the patch worked. Those PoCs also did not crash in this lab on 8.5.11 before the patch. I verified the patch’s effect by reading the GHSA descriptions and diffs. The lab verified only that the feature and the application-level chain remain after patching.

10.7 Remaining uncertainties

This lab did not reproduce the actual producer/consumer path for the official CVEs. It is an investigation based on the patch diffs and GHSA descriptions. Although PHP says RCE was demonstrated on mod_php, I did not reproduce RCE on my own machine; I keep those claims separate.
The GHSA says the FPM path for 619 “depends on appropriate application actions.” Which actions produce the state depends on the application and extension combination.
Impact on PHP 5.4–7.3 is not confirmed because those versions are outside the official scope. Backports exist for 7.4–8.1, but these are not supported updates.
I did not check for in-the-wild (ITW) attacks after the release.

11. Conclusion

There are five takeaways from this investigation:

Application-layer security and runtime security are different things. Your code can be perfectly fine and still be affected before a request reaches it.
The CVEs are real, and upgrading is the only complete fix. Upgrade to 8.5.12 / 8.4.27 / 8.3.36 / 8.2.35. Configuration cannot fully replace the patch.
The causes are OOM state corruption and state left behind across requests. This is not a zval UAF within one request. The first issue lets shutdown touch memory left in an invalid state during initialization; the second skips a reset after a fatal error/OOM, so the next request reads stale state.
session.upload_progress writes to the session before the application runs. This primitive is real, and combining it with an application-level LFI can lead to RCE. PHP also confirms it as a consumer for 619.
Separate configuration mitigations, patches, and application-sink removal. enabled=Off blocks the confirmed Session Upload Progress path for 619, but other paths and application-level LFI can remain.

I chose the title “The Return of the PHP2Shell Nightmare” because the incident felt familiar from previous PHP RCE scares. But this time, the nightmare was created less by a single UAF and more by information getting mixed up with things overlooked at the application layer. Reading the official patch revealed both that the public PoC’s explanation was wrong and that the CVEs were real. Incorrect public information does not mean there is no vulnerability; a real vulnerability does not mean every public PoC is correct. Test what you can reproduce in a local lab, then check the result against official primary sources. That is the most reliable approach, both during an embargo and after it ends.

References

PHP: News Archive 2026 — The October 20 notice, October 21 security advisories, and fixed releases.
GHSA-w8hw-w9fx-j79w — RCE via OOM corruption — Primary source for CVE-2026-109618, the OOM path, and mitigations.
GHSA-6wmf-4rv5-p3rp — RCE via stale global state — Primary source for CVE-2026-109619, producers/consumers, and Session Upload Progress.
php/php-src commit 31c0ea7d7f — “Avoid state corruption via bailout,” the fix for both CVEs.
PHP Manual — Session Upload Progress — Progress data is written before application execution; details of PHP_SESSION_UPLOAD_PROGRESS.
php/php-src — ext/session/session.c — php_session_rfc1867_callback, the enabled=0 early return, and session writes.
php/php-src — main/rfc1867.c — Multipart parser and global callback.
GMO Flatt Security Blog — php2shell — Japanese secondary analysis that labels its connection to Session Upload Progress as a hypothesis.
Sansec — php2shell — Summary of the disclosure and mitigations.
Huntress — php2shell Rapid Response — Situation at disclosure and detection perspective.
JackalSyn — PHP-UP-2026 — Analysis of the public bundle; its VALIDATION.md says no ASAN crash was observed.
Zer061/CVE-2026-109618 — Public PoC code; I could not reproduce 618/619 in my lab.
Investigation report — Experiment logs, nginx/Apache access logs, session files, and uid= evidence.
Post-patch comparison (8.5.12) — Results of rerunning the trigger, PoCs, and LFI chain on an 8.5.12 ASAN build.

I Tried Hono v5 RC: What Changed from v4, and What Breaks?

Hirohisa Tanaka — Tue, 20 Oct 2026 12:17:44 +0000

I Tried Hono v5 RC: What Changed from v4, and What Breaks?

Will your app break when you upgrade to v5? Mine did.

TL;DR

With the Hono v5 release candidate out, I set up separate v4 and v5 environments and ran identical code in both. I measured five areas: type checking, runtime behavior, routing, performance, and size.

Every type-related breaking change was caught by the type checker. Start your migration with tsc --strict.
The real risks are three changes the type checker won't catch: c.json(undefined), the composition of onError() handlers, and changes to wildcard matching.
“Smaller” refers to the installed package. The final bundle actually grew by 302 bytes.

Here is the environment I used:

Item	Value
Test date	2026-10-18
v4	`hono@4.13.13`
v5	`hono@5.0.0-rc.1`
Node.js	v24.22.0
TypeScript	7.0.2
Machine	Apple M4 (arm64)

Experimental code and raw data

Let me state my main takeaway up front:

The things that break in v5 are the places where v4 was permissive. c.req.json() returned any; c.req.query() concealed the possibility of undefined; and onError() silently overwrote previous handlers. Those were all places where v4's API gave a misleading picture. v5 is simply more honest. Migration may be inconvenient, but that is a different question from whether the design is sound.

This is a hands-on account of testing Hono v5 RC, written for Hono users who want to know what will break when they upgrade.

v5 is a release candidate. Behavior may change before the stable release. Everything here reflects testing on October 18, 2026.

1. Hono v5 Is “Hono for AI”

Before listing breaking changes, it's worth understanding what v5 is trying to accomplish. Once you see that, the individual changes start pointing in the same direction.

At Hono Conference 2026, creator Yusuke Wada described v5 as “Hono for AI.”

He described the goal of AI-friendly APIs as:

Abstracted, with fewer choices.

That was the key to understanding v5.

Changing c.req.json() so it no longer returns any, and turning onError() from a special function that can only be registered once into ordinary middleware, are part of the same idea: remove special cases and reduce the number of ways to do things.

A human might see any and reason, “Well, this will actually be a string, so it'll be fine.” When an LLM writes the code, that implicit assumption may not survive. If the types lie, the generated code can carry the same lie forward.

With that in mind, the changes below make a lot more sense.

2. Setting Up the Test Environments

I completely separated the directories to prevent v4 and v5 dependencies from mixing.

cd sandbox/v4
npm init -y && npm pkg set type=module
npm install hono@4
npm install -D typescript tsx @types/node

cd ../v5
npm init -y && npm pkg set type=module
npm install hono@next      # installed 5.0.0-rc.1
npm install -D typescript tsx @types/node

The RC is distributed under the next dist-tag. npm install hono@next is the method recommended by the official migration guide.

Here are the actual installed versions:

$ (cd sandbox/v4 && npm ls hono typescript)
v4@1.0.0
├── hono@4.13.13
└── typescript@7.0.2

$ (cd sandbox/v5 && npm ls hono typescript)
v5@1.0.0
├── hono@5.0.0-rc.1
└── typescript@7.0.2

$ node --version
v24.22.0

All tests used app.request() or app.fetch(). Since I didn't start an HTTP server, no runtime adapter was needed.

3. Stricter Types

`c.req.json()` Changes from `any` to `unknown`

In v4, this code passes type checking:

import { Hono } from 'hono'

const app = new Hono()

app.post('/users', async (c) => {
  const body = await c.req.json() // any

  return c.json({
    name: body.name.toUpperCase(), // TypeScript accepts this
  })
})

If a number is sent as name, the code crashes at runtime. The type system provides no protection.

Running the same code through tsc --strict with v5 gives:

src/typecheck-json.ts(9,11): error TS18046: 'body' is of type 'unknown'.

You now have to narrow the type before accessing its properties.

There are three approaches. The first one listed in the official guide is supplying a type argument:

const body = await c.req.json<{ name: string }>()

But this is not runtime validation. The type argument merely declares what you expect. You can still make a false declaration and the compiler will accept it. Personally, I think silencing the error this way misses the point of returning unknown: inspect the value before using it.

The straightforward alternative is a type guard. This passed v5's type checker:

app.post('/users', async (c) => {
  const body = await c.req.json()

  if (
    typeof body !== 'object' ||
    body === null ||
    !('name' in body) ||
    typeof body.name !== 'string'
  ) {
    return c.json({ error: 'Invalid body' }, 400)
  }

  return c.json({ name: body.name.toUpperCase() })
})

In real applications, the third option—using a validator and accessing the validated data through c.req.valid()—is usually the best choice. The official guide recommends it as well.

Destructuring `c.req.query()` Starts Producing Errors Everywhere

I think this change will affect more codebases:

const { name } = c.req.query()
const upper: string = name.toUpperCase()

const all = c.req.queries()
const tags: string[] = all.tag

This passes on v4. On v5:

src/typecheck-query.ts(7,25): error TS18048: 'name' is possibly 'undefined'.
src/typecheck-query.ts(10,9): error TS2322: Type 'string[] | undefined' is not assignable to type 'string[]'.
  Type 'undefined' is not assignable to type 'string[]'.

Calling query() without a key now has a return type of Record<string, string | undefined>. Consequently, destructured values start producing errors.

The Interesting Part: Runtime Values Are Unchanged

I sent GET /q?a=1&a=2 and compared the actual results.

	v4	v5
`c.req.query()`	`{"a":"1"}`	`{"a":"1"}`
`c.req.queries()`	`{"a":["1","2"]}`	`{"a":["1","2"]}`

They're identical.

In other words, v5 didn't change the runtime behavior. In v4, looking up a nonexistent key could already return undefined; the types merely insisted it was a string.

Only the types became more honest. Every newly flagged line was already a potential bug in v4.

4. Error Handling Has Been Redesigned

This is the most interesting v5 change to me.

What Changed?

In v4, onError() looked like this:

app.onError((err, c) => {
  console.error(err.message)
  return c.json({ error: 'Internal Server Error' }, 500)
})

There was one handler for the whole app, with the signature (err, c).

In v5:

// Path-scoped error middleware
app.onError('/api/*', async (c, next) => {
  console.error(c.error?.message)
  c.header('X-Error-Handler', 'api')
  await next()
})

// Omitting the path registers '*' under the current basePath
app.onError((c) => {
  return c.json({ error: 'Internal Server Error' }, 500)
})

The signature becomes (c, next), and you read the error from c.error. You can also specify a path and register multiple handlers.

The intention is stated explicitly in PR #5541:

The goal is to model error and not-found handling using Hono's routing system, including middleware composition, path scoping, sub-application handling, and Router-level decoration.

Error handling has been rebuilt on top of the routing system. Internally, the handlers are registered with reserved methods called @ERROR and @NOT_FOUND. That means error handlers are resolved using the same underlying mechanism as ordinary routes.

notFound() now follows the same pattern:

app.notFound(
  '/api/*',
  async (c, next) => {
    c.header('x-not-found', 'api')
    await next()
  },
  (c) => c.text('API resource not found', 404)
)

Measurement: Does Path Scoping Work?

I tested it directly:

Request	`X-Error-Handler`	Status	Body
`/api/error`	`api`	500	`{"error":"Internal Server Error"}`
`/other/error`	(absent)	500	`{"error":"Internal Server Error"}`

It works: only /api/* receives the extra header, while the common handler produces the final response.

Trying the same thing in v4 yields:

this.errorHandler is not a function

v4's onError() accepts only one argument. It saves the path string as if it were the handler, then fails when a request arrives. Registration itself doesn't complain. notFound() similarly threw TypeError: onNotFound is not a function.

Gotcha #1: Composition Instead of Overwriting

I expect this to be one of the biggest migration pitfalls.

I registered onError() twice and recorded which handlers ran:

	Handlers executed	Response
v4	`["second"]`	`second`
v5	`["first", "second"]`	`second`

v4 uses last-registration-wins replacement; v5 composes handlers.

Code that depended on a later registration replacing an earlier handler will now execute both.

When the first handler returns a response, the chain stops:

	Handlers executed	Response
v5	`["first"]`	`first`

Call next() to continue; return a response to stop. These are ordinary middleware rules.

And this won't produce a type error. Once you update the signature to (c, next), tsc passes. You may not notice the behavioral change until you actually run the app.

Gotcha #2: Old v4 Handlers Cause Confusing Runtime Errors

I also wondered what happens if you run a v4-style handler under v5.

First, the type checker correctly stops it:

src/typecheck-onerror-v4style.ts(7,21): error TS2339: Property 'message' does not exist on type 'Context<BlankEnv, string, any>'.
src/typecheck-onerror-v4style.ts(8,12): error TS2339: Property 'json' does not exist on type 'Next'.

It shows exactly what's changed: the first argument is now Context, and the second is Next.

But if you suppress those errors with @ts-expect-error and execute the code, you get:

Context is not finalized. Did you forget to return a Response object or `await next()`?

That message doesn't identify the root cause at all.

These were the arguments I observed:

{ "firstArgCtor": "Context", "firstArgIsContext": true, "secondArgType": "function" }

What your v4-style handler thinks is c is now the next function. It has no c.text(), so an exception occurs and the context never gets finalized. That's why the runtime reports this message.

Suppressing a type error can turn a straightforward migration fix into a long debugging session.

Throwing Values That Aren't `Error` Instances

In v4, throwing a string or object from a handler could escape past app.fetch().

In v5, the value is wrapped in an Error and sent to onError():

	v4	v5
`throw 'oops'`	Escapes outward	`message: 'oops'` / `cause: 'oops'`
`throw { code: 42 }`	Escapes outward	`message: ''` / `cause: { code: 42 }`

One detail matters: when you throw an object, message is empty. The original value appears only in cause.

app.onError((c) => {
  console.log(c.error?.message) // '' if an object was thrown
  console.log(c.error?.cause)   // { code: 42 }
  return c.json({ error: 'wrapped' }, 500)
})

If your logs only include c.error.message, you'll be left with an unhelpful empty entry. Check cause too.

Being able to catch strange thrown values from third-party libraries is a welcome improvement.

5. The Most Dangerous Change the Type Checker Won't Catch

The behavior of c.json(undefined) has changed.

	v4	v5
`c.json(undefined)`	200 / body length 0	500
`c.json(() => 1)`	200 / empty body	500

This is the actual exception thrown in v5:

TypeError: Value is not JSON serializable

The official explanation is that it now matches Response.json(). That makes sense.

The problem is that this does not produce a type error.

If a conditional expression can yield undefined and you pass it to c.json(), you can run tsc as many times as you like and it won't complain. Without a custom onError handler, the built-in handler returns 500, and you might discover the problem only in production.

Of all the migration checks in this article, I would prioritize this one the highest. You need tests to catch it.

One likely example is returning a database lookup directly:

const user = await db.query.users.findFirst({ where: eq(users.id, id) })
return c.json(user) // undefined if no user is found

In v4, an overlooked missing-user case could return 200 with an empty body rather than the intended 404. In v5, it becomes a 500. That means many of the new 500s were bugs already present in v4—v5 merely exposes them.

Another possible case is passing the return value of a void function directly. TypeScript might catch that when the type is void, but it can slip through if any is involved.

6. Wildcard Matching Is Now Consistent

In v4, Different Routers Gave Different Results

I registered the same routes in four routers under v4 and exhaustively checked the matches.

Route	Path	SmartRouter	RegExpRouter	TrieRouter	PatternRouter
`/x*/y`	`/x/y`	❌	❌	❌	❌
`/x*/y`	`/xz/y`	✅	✅	❌	❌
`/x*/y`	`/x/z/y`	❌	❌	❌	❌
`/x*y`	`/xay`	✅	✅	❌	❌
`/wild/*/card`	`/wild//card`	❌	❌	✅	❌
`/wild/*/card`	`/wild/a/card`	✅	✅	✅	✅

The results disagreed in three of six cases.

For /wild/*/card, only TrieRouter matched /wild//card. In other words, switching routers could silently change which paths matched.

In v5, All Four Routers Agree

I repeated the same checks under v5:

Route	Path	SmartRouter	RegExpRouter	TrieRouter	PatternRouter
`/x*/y`	`/x/y`	✅	✅	✅	✅
`/x*/y`	`/xz/y`	✅	✅	✅	✅
`/x*/y`	`/x/z/y`	❌	❌	❌	❌
`/x*y`	`/xay`	❌	❌	❌	❌
`/wild/*/card`	`/wild//card`	❌	❌	❌	❌
`/wild/*/card`	`/wild/a/card`	✅	✅	✅	✅

All four agree, matching the table in the official documentation.

The rules are now:

A * at the end of a segment is a wildcard; it can match an empty remainder.
A * in the middle of a segment, as in /x*y, is not a wildcard.
A segment consisting of just * matches one nonempty segment.

The changed results are /x*/y versus /x/y (❌ → ✅ in every router), and /x*y versus /xay (✅ → ❌ for the regex-based routers). These changes also escape static type checking.

Gotcha #3: Adding One Route Changes the Router

This was the most interesting discovery of the whole experiment.

If you register both /x*/y and /x/*, v5's RegExpRouter cannot handle the combination:

UnsupportedPathError: /x/*

SmartRouter catches that exception and falls back to TrieRouter.

I checked which router the app eventually selected:

Registered routes	Router selected in v5
`/x/*` only	`SmartRouter + RegExpRouter`
`/x/y` + `/x/`	`SmartRouter + TrieRouter`

Adding a single route changed the router used at runtime.

And when I tested those conflicting routes under v4 and v5, even the selected handler differed:

	v4	v5
Request to `/x/y`	Handler for `/x/*`	Handler for `/x*/y`

Routing can change silently, making this difficult to spot without targeted tests.

Measurement: How Much Does Fallback Cost?

A different router should affect performance, so I measured 50,000 requests to GET /users/:id across 12 rounds.

	Router	Median	Mean	Minimum
No conflict	`SmartRouter + RegExpRouter`	138.68 ms	152.28 ms	132.35 ms
Conflict	`SmartRouter + TrieRouter`	148.57 ms	163.99 ms	146.25 ms
Difference		+7.1%	+7.7%	+10.5%

The fallback was slower on all three measures.

A disclosure: I reran this benchmark. With just three rounds, I initially measured a 3.3% difference. On rerunning it, I got 8.1%. Three rounds weren't enough for a stable conclusion.

Even after increasing the count to 12 rounds, the raw data contained outliers such as 287 ms and 271 ms (possibly from garbage collection or OS scheduling). I therefore consider the +10.5% difference in minimum times, which is less affected by those outliers, closer to the underlying cost.

Why Would It Be Slower?

According to the official documentation, RegExpRouter compiles registered routes into one large regular expression and obtains a match in a single operation. TrieRouter uses a trie and supports the complete range of patterns, but isn't as fast as RegExpRouter.

SmartRouter defaults to [new RegExpRouter(), new TrieRouter()]. It tries the faster router first, then selects the more general implementation if necessary, continuing to use its choice thereafter. The design is essentially: try the fast one; fall back to the fully featured one if needed.

This test exercised that fallback path, so a performance difference was expected.

With RegExpRouter's consolidated expression, I would expect matching costs to remain fairly stable as routes are added. TrieRouter traverses a tree, so I would expect costs to depend on path segments and the route structure. If that's correct, the 7–10% gap I measured in this small app might be larger in an app with hundreds of routes.

Conversely, in a small application the fallback probably won't be noticeable.

But the exact 7–10% isn't the most important part. The bigger issue is that adding one route can silently switch the router. You won't see that in the logs or the types.

And this might be about more than speed. As shown above, a change in router selection can affect which handler matches. My measurements established that across v4 and v5; I suspect combinations and registration order within v5 could expose related issues, but I didn't test that hypothesis fully.

7. Is It Faster?

I also benchmarked the core routing performance.

Caution: this is an in-process microbenchmark using app.fetch().
It does not represent real HTTP-server or production Cloudflare Workers performance.
It includes no network, TLS, or process-boundary costs.

I ran 100,000 requests to GET /users/:id, with 20,000 warmup requests, alternating v4 and v5 for 10 rounds.

Statistic	v4	v5	Difference
Median	270.53 ms	266.50 ms	v5 1.5% faster
Mean	278.24 ms	271.85 ms	v5 2.3% faster
Minimum	258.31 ms	255.59 ms	v5 1.1% faster

My conclusion: the difference is within benchmark noise.

v5 was slightly faster by each metric, but the distributions overlap substantially: v4's minimum (258.31 ms) is lower than v5's median (266.50 ms). This test doesn't justify claiming that v5 is faster.

Benchmarks Without Round Counts Are Hard to Interpret

Another disclosure: at five rounds I measured a 2.9% difference. After increasing the test to ten rounds, it fell to 1.5%.

Same code, same machine, same day. Changing only the number of rounds nearly halved the apparent advantage.

The router fallback benchmark behaved similarly (3.3% at three rounds; 7.1% at twelve).

When discussing single-digit percentage differences in microbenchmarks, publishing the round count and the distribution matters. I learned that firsthand. Every measurement in this article includes its round count.

And unchanged core routing performance isn't bad news. Performance isn't the primary goal of v5's redesign.

8. What Actually Got “Smaller”?

In v5, runtime adapters were moved out of the core hono package into separate @hono/* packages. I expect people to describe that as “making Hono lighter,” so I measured what actually became smaller.

Installed Package Size Really Did Shrink

I queried the npm registry's unpackedSize field:

	Unpacked size	File count
`hono@4.13.13`	1.23 MB	574
`hono@5.0.0-rc.1`	0.66 MB	310
Difference	-46%	-46%

Running du -sh on my local node_modules showed 2.8 MB → 1.5 MB, also -46%.

Yusuke Wada's Hono Conference 2026 presentation reported 1.29 MB → 0.70 MB, again -46%, with file counts of 574 → 310. The file counts matched exactly. The slightly different absolute sizes probably reflect differences in the referenced versions.

Three independent ways of looking at it produced the same reduction. I think that number is trustworthy.

But the Bundle Got Bigger

Here's the catch: I built actual bundles with esbuild.

Entry point	v4	v5	Difference
Core only	18,528 B	18,830 B	+302 B (+1.6%)
With adapter	22,760 B	22,923 B	+163 B (+0.7%)

It increased rather than decreased.

Thinking about it, that makes sense. The package shrank because the CJS build was removed and adapters were split into separate packages. A CJS build that your bundler never used wasn't contributing to the bundle anyway. And once you install @hono/bun, the adapter code still comes along.

Code previously excluded by tree shaking has simply been separated at the package level. The amount of code ultimately bundled hasn't meaningfully changed.

When saying “Hono v5 is lighter,” specify whether you mean installation size or final bundle size. The first is true; the second was not supported by my measurements.

9. ESM-Only Packaging and Adapter Separation

It's ESM-Only, but `require()` Still Works

v5 removes the CJS build and becomes ESM-only. The official guide requires Node.js 22.12 or later.

Interestingly, under that requirement, require('hono') still works.

Test	Result
`require('hono')` in v4	OK
`require('hono')` in v5	OK
`import('hono/bun')` in v4	Resolves
`import('hono/bun')` in v5	`ERR_PACKAGE_PATH_NOT_EXPORTED`

Node.js 22.12 and later support loading eligible ESM modules with require(), so using require() doesn't necessarily fail just because a package is ESM-only. The official guide mentions this, and my test confirmed it.

However, subpaths such as hono/bun have disappeared from exports, so those definitely break. The issue is not necessarily CommonJS-style loading; it's the old subpath imports.

All Eight Adapters Were Published on September 28, 2026

I checked their initial publication dates in the npm registry.

Package	First published
`@hono/bun` / `@hono/deno` / `@hono/cloudflare-workers`	2026-09-28
`@hono/vercel` / `@hono/netlify`	2026-09-28
`@hono/aws-lambda` / `@hono/lambda-edge`	2026-09-28
`@hono/service-worker`	2026-09-28

All eight released version 1.0.0 on the same day. They're the packages split out for v5.

@hono/node-server is not one of these eight. Its first release was on January 7, 2023, and it was already a separate package during v4. Don't confuse it with the newly extracted adapters.

Adapter Separation and Supply-Chain Security

I had heard the argument that separating adapters could reduce the attack surface for supply-chain compromises. I decided to investigate.

On June 23, 2026, Yusuke Wada presented “Hono Supply Chain Compromise Countermeasures: Lessons from Three Libraries” at GMO Flatt Security's meetup on what OSS developers should do about software supply-chain attacks.

The three case studies were axios, TanStack, and Mastra, each with a different attack path:

Library	Attack path
axios	Social engineering: malware on a maintainer's machine stealing credentials
TanStack	Cache poisoning through `pull_request_target` (“Pwn Request”); possible even without merging the PR
Mastra	npm account takeover

Among the Hono-side mitigations was removing adapter functionality from the core. Other measures included:

Moving npm publishing from local machines to GitHub Actions with OIDC trusted publishing.
Avoiding pull_request_target.
Pinning GitHub Actions to lock down the environment.
Removing Dev Containers and Gitpod configuration.

This suggests adapter separation is not only about package size; it's also about reducing the attack surface. Size and file count were emphasized at Hono Conference 2026, but the same change had been discussed in a security context back in June.

But It Doesn't Reduce the Dependency Count

Here's something I verified myself.

I queried npm registry metadata for dependencies:

	Runtime dependencies
`hono@4.13.13`	0
`hono@5.0.0-rc.1`	0
`@hono/bun@1.0.1`	0 (only `hono` as a peer)

For comparison, express had 28 and axios had 4 in the registry data I checked.

Hono already had zero external runtime dependencies in v4. Splitting adapters didn't reduce that count. It's zero in both versions.

What decreased was the amount of code shipped in the core package. As shown in section 8, the file count dropped from 574 to 310.

For a zero-dependency library, the package's own distributed code is itself part of the supply-chain attack surface. In that sense, removing adapters is better understood not as shrinking the dependency graph, but as roughly halving the code shipped together in a single package.

10. `defineHandler()`: The “Fewer Choices” Philosophy in Action

The experimental defineHandler() API is the clearest example of the “abstracted, with fewer choices” goal from section 1. I tried it because it shows where the design is heading.

The simplest example is:

import { defineHandler } from 'hono/factory'

app.get('/ping', defineHandler(() => ({ pong: true })))

ping -> 200 {"pong":true}

There's no c.json(). The returned value is converted into a Response. An object becomes JSON, a string or JSX becomes HTML, and null or undefined produces a 204.

Request and response validation can also be defined in one place:

app.post(
  '/users',
  defineHandler({ json: NameSchema })((c, input) => ({
    name: input.json.name.toUpperCase(),
  }))
)

NameSchema can be anything implementing Standard Schema, including Zod schemas.

With invalid input, I received:

schema ng -> 400 {"error":"Validation failed","issues":[{"slot":"json","issues":[{"message":"name must be a string","path":"name"}]}]}

I ran into one surprise: if you pass an ordinary validation function rather than a Standard Schema and throw inside it, you get a 500 instead of a 400.

invalid -> 500 Internal Server Error

Because the API also accepts validation functions, I assumed failures would be handled identically. But in my testing, only the Standard Schema path wrapped failures into an HTTPException that returned 400. If you need that 400 response, use the Standard Schema format.

And the type definition contains a comment that captures the philosophy perfectly:

A JSON Response by c.json() is not accepted, because it bypasses the response validation. Return the value instead.

Returning c.json() is explicitly forbidden by the types, because doing so would bypass response validation.

This is a shift from “several approaches usually work” to “there's one preferred approach and the types prevent alternatives.” It's a concrete expression of the design goal described earlier.

Note that defineHandler() is experimental and may change before the stable release.

11. Migration Checklist

Here are my priorities based on what I actually measured.

First, Run `tsc --strict` (Type-Detectable Changes)

Direct property access on the result of c.req.json().
Destructuring such as const { x } = c.req.query().
Treating c.req.queries() values as guaranteed string[].
Changing app.onError((err, c) => ...) to (c) => ... and reading c.error.

The compiler will point these out. You can fix them systematically.

Next, Fix the Three Changes Types Can't Detect

Any place that might pass undefined to c.json(): it now returns 500. Without tests, this is easy to miss.
Multiple registrations of onError() or notFound(): handlers compose rather than overwrite one another.
Routes containing wildcards: /x*/y now matches /x/y.

This is the real migration work. Passing the type checker is not enough.

Also look for conflicting routes such as /x*/y and /x/*, which can trigger router fallback.

Update Imports and Removed APIs

hono/<runtime> → @hono/<runtime> (eight packages).
hono/cloudflare-pages: no direct replacement; migrate to Workers.
app.mount() → mount() from hono/mount.
app.fire() → fire(app) from @hono/service-worker.
c.req.routePath / c.req.matchedRoutes → hono/route.
getColorEnabledAsync() → getColorEnabled(c.env).
toSSG() hook options → plugins (explicitly include defaultPlugin() when needed).

One small detail: UnOfficalStatusCode was corrected to UnofficialStatusCode. A long-standing typo from v4 has finally been fixed.

12. What I Didn't Verify

I couldn't investigate everything. Here are the remaining questions:

Priority of sub-app notFound() handlers when they're integrated via route(). The PR describes deeper-nested sub-apps taking priority, and registration order breaking ties at the same depth, but I didn't test it.
How basePath() interacts with onError() path resolution.
Benchmarks through a real HTTP server; all my measurements used app.fetch().
Performance in an actual Cloudflare Workers environment.
Integration of @hono/zod-validator with c.req.valid().
Hono CLI 1.0 RC.

And again, v5 was still an RC during testing. These behaviors could change before the stable release.

13. Conclusion

What struck me most was this: the places that break in v5 are the places v4 was too permissive.

The any from c.req.json() and the overly confident string types from c.req.query() gave developers misleading information. v5 stops doing that. The actual query behavior hasn't changed at all. Making onError() composable similarly replaces a special-case singleton with ordinary middleware.

The direction is consistent with “abstracted, with fewer choices.” Even defineHandler() rejecting c.json() through the type system follows the same philosophy.

The migration cost isn't negligible. Fortunately, tsc --strict highlights much of it. The three things to watch most closely are the changes static types don't detect: c.json(undefined), composition of onError() handlers, and wildcard matching. You'll need tests or manual inspection for those.

Performance was effectively unchanged. Installation size dropped by nearly half, but bundle size did not. The reason to upgrade to v5 isn't speed or bundle size; it's a cleaner, more consistent API design.

Would I deploy the RC to production today? No, I'd wait for stable. But running a build of an existing project against hono@next is absolutely worthwhile. The resulting type errors will immediately give you an idea of the migration effort.

Finally, two predictions for the stable release:

If one of these changes gets revised, I think it'll be defineHandler(). It's explicitly marked experimental, and behavior such as “throwing in a validation function returns 500 rather than 400” still has rough edges. Conversely, the onError() redesign and wildcard unification seem well specified in their PRs and implemented thoroughly, so I expect them to remain.

My guess is that the removal of hono/cloudflare-pages will cause the most migration pain. Most changes can be fixed by rewriting code, but this one has no direct replacement and requires a separate move to Workers. c.req.query() may produce far more type errors, but those are mechanical fixes. A single change without a drop-in replacement can cost more time than hundreds of compiler errors.

I'll revisit these predictions when the stable version arrives.

As for my project? It broke, just as expected.

References

Migrating to v5 — Hono — Official breaking-change guide; the source for my test cases.
feat!: add routable error and not-found middleware (honojs/hono#5541) — onError() / notFound() redesign, reserved route methods, and sub-app priority rules.
Hono Conference 2026 — Yusuke Wada — The “Hono for AI” framing and package size figures.
honojs/hono releases — Release dates of 5.0.0-rc.0 (2026-10-08) and 5.0.0-rc.1 (2026-10-10).
Hono Supply Chain Compromise Countermeasures — Yusuke Wada — Case studies of axios, TanStack, and Mastra; adapter extraction as a mitigation. (Japanese)
“What Should OSS Developers Do Now?” meetup report — kouki_engineer — Attendee report on the June 23, 2026 GMO Flatt Security meetup. (Japanese)
npm registry: hono — Source for dependencies, unpackedSize, and fileCount.
Standard Schema — Common schema interface accepted by defineHandler().
Routers — Hono — RegExpRouter, TrieRouter, SmartRouter, and default selection.
Mount Middleware — Hono — Migration destination for the removed app.mount().

I Tested Google's DPoP Implementation. The Documentation Told a Different Story.

Hirohisa Tanaka — Tue, 20 Oct 2026 05:13:06 +0000

The implementation worked. It was the documentation that let me down.

TL;DR

I investigated Google's mechanism for binding OAuth refresh tokens to a cryptographic key using DPoP from four angles: the official documentation, RFC 9449, my own measurements, and actual token exchanges. The implementation itself worked as intended. Every obstacle I encountered came down to a difference between the documentation and observed behavior.

The differences fell into three categories:

Different from the RFC: Access tokens remain Bearer tokens, and jti isn't random in the authorization-code flow. These are design choices documented by Google.
Different from what the documentation claims: An official example contains an incorrectly encoded signature, different documentation pages contradict one another, and the claim that "a nonce value is used only once" doesn't match observed behavior.
Not documented at all: The accepted iat window and the order in which the grant and DPoP proof are validated. I had to measure these myself.

Here's the environment I used:

Item	Value
Test date	October 19, 2026
Node.js	v24.22.0
`jose`	6.2.12
`hono`	4.13.13
Machine	Apple M4 (arm64)

Implementation: GitHub repository

Let me make the main point clear up front.

Google's DPoP implementation is not fundamentally broken. Its design decisions have reasons behind them, and the performance argument held up in my measurements. The frustrating part for implementers is that some documented behavior differs from reality, while important details aren't documented at all. I reported the "used only once" discrepancy to Google, but the report was closed as Won't Fix. In other words, this was treated as a documentation discrepancy rather than a demonstrated security vulnerability.

This article expands on my lightning talk, "Google OAuth Apparently Supports DPoP Now, So I Tried It," with measurements and analysis I couldn't fit into the presentation. It is intended for developers who store Google API OAuth refresh tokens on their servers.

1. What is DPoP?

DPoP (Demonstrating Proof-of-Possession) is an OAuth 2.0 security mechanism standardized in RFC 9449. It became a Proposed Standard in September 2023, and providers such as Okta and FusionAuth have supported it for some time. What's new is Google's support, not DPoP itself.

A conventional Bearer token follows what Google's blog calls the "finders-keepers model": whoever gets the token can use it. DPoP helps prevent this through sender-constraining:

The client generates a key pair and keeps the private key to itself.
For each request to the token endpoint, the client includes a JWT signed with its private key (a DPoP proof).
The server issues a token bound to the public key.

sequenceDiagram
    participant C as Client (BFF)
    participant G as Google OAuth
    Note over C: Generate an EC P-256 key pair
    C->>G: Authorization code exchange + DPoP proof
    G-->>C: refresh_token (key-bound)<br/>access_token (Bearer)<br/>DPoP-Nonce
    Note over C: Sign each subsequent refresh proof<br/>with the same key
    C->>G: refresh_token grant + DPoP proof
    G-->>C: New access_token + new DPoP-Nonce

I ran the tests against a Node.js + TypeScript server acting as a Google OAuth confidential client. For JWTs I used jose 6.2.12, which provides ES256 signing and JWK export without additional dependencies. I used a dedicated test client and account; I did not touch any production user's authorization grants.

2. Even the date of support was different from what I expected

Google announced the feature on the Developers Blog on October 15, 2026. But when I checked revisions of the official documentation through the Wayback Machine, the timeline didn't quite line up.

Date	Event
April 15, 2026	No mention of DPoP in Best Practices
May 20, 2026	"Sender-constrain tokens with DPoP" appeared in Best Practices
July 31, 2026	Last update to the DPoP Adoption Guide
September 4, 2026	Google's official DPoP `SKILL.md` committed to `google/skills`
October 15, 2026	Announcement on the Developers Blog
October 16, 2026	Web-server documentation updated for DPoP

Judging from the documentation, support was present by at least May—about five months before the blog announcement. I'm not suggesting anything was concealed; an official blog post's publication date is not necessarily a feature's release date.

And that was just the beginning. The more I verified, the more differences I found, and they fell rather neatly into three categories.

3. Difference #1: Different from the RFC (documented design choices)

RFC 9449 leaves certain optional decisions to the authorization server. Google's choices differ from the general RFC model, but these differences are documented. If you implement solely from the RFC, though, they can still trip you up.

Access tokens remain Bearer tokens

RFC 9449 §5 specifies DPoP as the token_type using MUST language. However, Google's web-server documentation explicitly says that token_type will always be Bearer, even when using DPoP. Only refresh tokens are bound to keys.

This isn't necessarily an RFC violation. The RFC allows an exception in which only the refresh token is sender-constrained when a public client also receives a refresh token.

According to Google's blog, the motivation is performance: avoid the cost of checking asymmetric signatures on every request to a high-QPS API. I measured that cost using a loop of 20,000 operations on Node v24.22.0 / Apple M4.

Operation	µs/op	ops/s
ES256 sign	26.2	38,227
ES256 verify	50.5	19,787

Verification took about twice as long as signing, with throughput around 20,000 verifications per second per core. At my application's scale, that overhead is negligible. At Gmail or Drive scale, it matters. Google's performance argument seems reasonable.

`jti` isn't random during the authorization-code exchange

RFC 9449 §4.2 requires the jti claim to contain at least 96 bits of pseudorandom data or a UUIDv4. Google, however, uses a deterministic value specifically during the authorization-code exchange:

the value of jti is the Base-64 and Url-encoded SHA256 hash of the authorization code, such as jti = BASE64URL(SHA-256(authorization_code))

I checked this using the authorization code and jti from Google's official example:

import hashlib, base64
code = "4/0AXEQxIDNpLD-qpSIvjHb2Hl10uS_2sk2GBRpO8UJQ78YZF3hZ9LB9kTA1xYLD4xisi4C5w"
print(base64.urlsafe_b64encode(hashlib.sha256(code.encode()).digest()).rstrip(b"=").decode())
# -> o29CN8LIY0l_N8iy5-ilon1guad9NFQHFOdXTzrBNck (matches the example's jti)

It matched. For refresh requests, Google instead uses an ordinary random value (192 bits). The same jti claim is generated according to different rules in different flows. Implement only one of them, and you'll run into trouble.

Why? The mechanism prescribed by RFC 9449 for binding an authorization code to a key is the dpop_jkt authorization request parameter in §10. Google's authorization request doesn't include dpop_jkt. Instead, it reuses the existing jti claim. Since an authorization code is single-use, the deterministic value is effectively unique for this purpose. My reading is that Google used an existing claim instead of implementing an optional RFC mechanism.

Binding tokens even for confidential clients

RFC 9449 §5 says:

Refresh tokens issued to confidential clients ... are not bound to the DPoP proof public key because they are already sender-constrained with a different existing mechanism.

Yet Google's Adoption Guide example is a confidential client that sends a client_secret. Meanwhile, Best Practices strongly recommends DPoP for public clients such as SPAs and installed apps, but recommends placing a BFF (a confidential client) in front of an SPA. You want to protect a public client, but the recommended architecture turns it into a confidential-client implementation.

The RFC even notes that client authentication is more flexible than key binding, because it allows a key to be changed without invalidating the refresh token. Google's design knowingly incurs the trade-off that warning describes.

4. Difference #2: The documentation says one thing; the implementation does another

Now for the main event.

An official example contains an incorrectly encoded proof signature

The Adoption Guide contains two sample proofs. I was planning to reuse them, but decided to verify their signatures first. That's where I got stuck.

Example	Signature length	Result
Authorization-code exchange	64 B	SIGNATURE VALID
Token refresh	70 B	SIGNATURE FAILED

When I parsed the 70-byte signature as ASN.1, it parsed cleanly:

hex head: 30 44 02 20 ...
ASN.1 DER SEQUENCE? True | declared len: 68
  r: tag=0x02 (INTEGER) len=32
  s: tag=0x02 (INTEGER) len=32

JWS requires a raw R || S signature (64 bytes for P-256, in IEEE P1363 format), but the example includes an ASN.1 DER-encoded signature. Google's own web-server documentation specifically warns against doing this:

Note that JWS requires the signature to be in a raw R | S concatenated format (64 bytes for P-256). If using OpenSSL directly, you must convert the default ASN.1 DER-encoded signature to this raw format.

You can reproduce the trap within Node.js itself. Even for ES256, different APIs produce different signature formats:

crypto.subtle.sign     -> 64 bytes, first byte 0xed   (raw P1363)
node:crypto createSign -> 71 bytes, first byte 0x30   (ASN.1 DER)

The node:crypto result was DER-encoded and 71 bytes long, while Google's example was 70 bytes. DER signature lengths vary—roughly 69–72 bytes depending on leading zeros—so don't attempt to identify DER just by checking length === 70.

Another detail: when I decoded the sample proof in the web-server documentation, it turned out to be copied straight from the example in RFC 9449. Its htu is https://server.example.com/token (not Google's endpoint), its iat is 1562262616 (July 4, 2019), and its jti violates Google's own rule stated just three paragraphs earlier. Copy it verbatim, and the htu mismatch gets rejected.

The documentation contradicts itself about carrying a nonce into the next workflow

Can you take the DPoP-Nonce returned by an authorization-code exchange and use it for the first refresh? Two Google documents give opposite answers:

Adoption Guide (July 31, 2026): Crossing workflows causes an unconditional HTTP 400 rejection.
Web-server documentation (October 16, 2026): Reusing this nonce avoids an extra round trip.

I tried it. The result was HTTP 400 use_dpop_nonce. The older Adoption Guide matched reality; the newer web-server documentation did not. The first refresh therefore requires a 400 → retry sequence, costing two round trips. A use_dpop_nonce retry loop is required, not an optimization. Without it, the first refresh immediately after authorization fails.

The documented error codes don't match

The web-server documentation says that a mismatched htm/htu, an expired iat, a reused proof, or an invalid signature all yield invalid_dpop_proof. My tests found otherwise:

Documentation says	Observed	Match?
`htu` mismatch → `invalid_dpop_proof`	`invalid_request`	❌
`htm` mismatch → `invalid_dpop_proof`	`invalid_request`	❌
Expired `iat` → `invalid_dpop_proof`	`invalid_dpop_proof`	✅
Invalid signature → `invalid_dpop_proof`	`invalid_dpop_proof`	✅

The observed categories were more consistent than the documentation suggests:

Condition	`error`
Missing proof / mismatched `htm` or `htu`	`invalid_request`
Invalid signature / `iat` outside accepted range	`invalid_dpop_proof`
Missing, expired, or cross-workflow nonce	`use_dpop_nonce`
Invalid authorization grant	`invalid_grant`

`extractable: false` doesn't translate cleanly to Node.js

Google's official SKILL.md calls this a "CRITICAL SECURITY GUARDRAIL":

The private key MUST be configured as non-extractable (extractable: false).

But if you follow that instruction literally in Node.js, you can no longer persist the key:

exportKey('jwk')   -> InvalidAccessError: key is not extractable
exportKey('pkcs8') -> InvalidAccessError: key is not extractable

A non-extractable key can't be exported from the process. When the server restarts, every user's refresh token bound to that key becomes unusable; the only recovery is to get users to authorize again.

Also, Node.js WebCrypto does not inherently provide a TPM or Secure Enclave. A non-extractable key is just a key held in process memory; Node doesn't provide the "hardware cryptographic boundary" described in SKILL.md. This wording is geared toward browsers or mobile environments, not the Node confidential-client example assumed by the Adoption Guide.

In practice, you need a persistent key strategy: for example, generate with extractable: true, then protect the exported JWK using encryption or KMS. That works, but it means private-key material is now stored outside the process, potentially in your database.

The "a nonce value is used only once" claim didn't hold up

The Adoption Guide says:

Note that a nonce value is used only once and a missing, invalid, expired, or reused nonce value is rejected with an HTTP 400 response.

First, I tested whether nonces were validated at all. Both a completely bogus nonce and a nonce altered by one character were rejected with 400 use_dpop_nonce. Validation was happening.

Next, I used the same nonce repeatedly:

1st request (same nonce)       200
2nd request (same nonce)       200
3rd request (same nonce)       200
4th request (same nonce)       200
5th request (same nonce)       200
30 seconds later (same nonce)  200

All six succeeded. The nonce was validated, but not consumed.

The same appeared to happen with jti. The web-server documentation says a reused jti causes invalid_dpop_proof, yet two proofs with the same jti both returned 200. I found no evidence that the server was tracking used jti values in these tests.

Together, those behaviors meant I could replay an identical proof byte for byte. Sending a proof with exactly the same jti, nonce, iat, and signature repeatedly returned 200 and issued a new access token each time. I recorded SHA-256 hashes of the submitted proof and the returned tokens. Identical proof hashes resulted in different token hashes, indicating actual reissuance rather than a cached response.

How long would that work? I created one proof and replayed it over time, matching the conditions of a captured proof in which both iat and nonce age together. There was no shortcut for this test; I left my terminal open for an hour.

Elapsed time since proof creation	HTTP	Result
0–2700 s (0–45 min)	200	Replay accepted
3300 s (55 min)	200	Replay accepted
3540 s (59 min)	200	Replay accepted
3660 s (61 min)	400	`invalid_dpop_proof`

It succeeded at 59 minutes and failed at 61 minutes with invalid_dpop_proof, not use_dpop_nonce. The nonce was still accepted at 59 minutes, so the iat window appeared to expire first. In this test, a captured proof could be replayed repeatedly for approximately one hour after issuance.

RFC 9449 §11.1 directly addresses this situation:

Unlike cryptographic nonces, it is acceptable for clients to use the same nonce multiple times ... As long as the jti value is tracked and duplicates are rejected for the lifetime of the nonce, there is no additional risk of token replay.

The RFC allows nonce reuse provided the server tracks jti and rejects duplicates. In my tests, Google's endpoint accepted reused nonces and didn't appear to reject repeated jti values. That means the condition attached to the RFC's nonce-reuse allowance wasn't met in the observed behavior.

5. Difference #3: Things the documentation doesn't tell you

These are the details I needed for implementation but couldn't find documented. I had to measure them.

The grant is validated before the proof

I supplied a nonexistent refresh token while deliberately corrupting the proof in eight different ways. Even with a DER-encoded signature, a malformed typ, or simply not-a-jwt, every request returned invalid_grant and none returned DPoP-Nonce.

Here's the practical consequence: a grant error can conceal bugs in your proof during debugging. If your refresh token has expired, you may only see invalid_grant, no matter how broken the proof is. This can explain the frustrating "I fixed the proof, but it still doesn't work" experience.

The best debugging sequence is to verify that refresh works without DPoP first, then add DPoP. That way you can isolate the source of failure.

The accepted `iat` window

Google says expired iat values are rejected but doesn't publish an exact tolerance. RFC 9449 §4.3 leaves that detail to implementers. I narrowed it down to the second using binary search, with matching results from two independent runs.

Direction	Furthest accepted	Nearest rejected	Boundary
Past	-3599 s	-3600 s	Exactly 3600 s
Future	+10 s	+11 s	Exactly 10 s

3600 seconds into the past, but only 10 seconds into the future: a 360× asymmetry. A generous past window accounts for delays before a proof reaches the server. A tight future window discourages proof pre-generation, which is discussed in RFC 9449 §11.2, "DPoP Proof Pre-generation." The ~one-hour replay window from §4 was governed by the same past-side 3600-second limit. Two independently measured values pointed to the same boundary.

One practical lesson: a server clock just 11 seconds ahead can cause every proof to be rejected. If you're seeing unexplained invalid_dpop_proof errors on a machine without working NTP synchronization, check its clock.

Other undocumented details

The challenge field in successful responses. It appears in an Adoption Guide example but isn't explained in the prose. Its value matched the DPoP-Nonce header.
No DPoP advertisement in discovery. RFC 9449 §5.1 defines authorization-server metadata named dpop_signing_alg_values_supported. When I queried accounts.google.com/.well-known/openid-configuration, I found no keys containing dpop. A standards-based client relying on discovery for feature detection cannot discover Google's DPoP support this way.
The algorithm name for RSA. The Adoption Guide allows RSA but only says it's not recommended because of computational cost. It doesn't specify RS256 versus PS256, and discovery doesn't list either. You have to try it to find out.

6. I reported it, and the result was Won't Fix

I reported the last issue from §4—no apparent jti tracking, nonce reuse, and replayable proofs—to Google Bug Hunters. It conflicted with the documentation and appeared to miss a condition described in the RFC's replay-hardening guidance. I attached reproduction logs with secrets replaced by irreversible hashes.

The result was Won't Fix (Infeasible). Google's reasoning, in summary:

I hadn't demonstrated account takeover, privilege escalation, or an independent authentication bypass.
I had acknowledged that the practical impact appeared limited.
The report didn't meet the Vulnerability Reward Program threshold of a meaningful compromise to another user's data confidentiality or integrity.

I agree with that assessment. An attacker in a position to observe the proof (for example, through an adversary-in-the-middle setup, a TLS-terminating proxy, or logs) could also capture the refresh_token and client_secret from the same request body. And as shown in §5, a proof alone is rejected with invalid_grant; replay requires a valid refresh_token. The replay window did not establish an additional attacker capability in the scenario I tested.

In that sense, the response helped clarify the nature of the finding: an observed discrepancy between implementation and documentation, not a demonstrated exploitable security vulnerability. That is the core message of this article.

It's still worth documenting. Statements like "a nonce value is used only once" and "a reused jti is rejected" lead implementers to expect behavior that I couldn't reproduce. You might implement unnecessary synchronization—or rely on a replay defense that isn't behaving as documented. The report and its outcome are another reminder not to treat official documentation as a substitute for testing.

7. Should you adopt DPoP?

DPoP binding is valuable when you store refresh tokens long-term and want to reduce the risks of that storage being compromised. If a database dump or log leak exposes only a refresh token, an attacker cannot use it without the corresponding key. That's a meaningful benefit.

Its protection is narrower than it might seem, though. Access tokens remain Bearer tokens and can still be used until they expire. Google's blog explicitly says that browser session cookies are outside DPoP's scope, pointing instead to DBSC for that problem. As discussed in §4, on Node.js the private key still needs to be persisted somewhere, weakening the simplistic assumption that "the key never leaves the device."

The biggest adoption cost is migration. To move existing users with unbound refresh tokens to DPoP-bound refresh tokens, you need to revoke the old grant or get a new token using prompt=consent. For a running service, that means asking every existing user to consent again. Key rotation introduces the same issue: obtaining a refresh token bound to a new key requires reauthorization. In other words, your private-key backup strategy effectively becomes your refresh-token backup strategy.

8. Conclusion

Google's DPoP implementation works. Its design choices have rational motivations, and my measurements supported its performance argument for leaving access tokens as Bearer tokens.

The difficulties all came from documentation gaps: differences from the RFC that are documented (§3), claims that don't match observed behavior (§4), and details that aren't documented at all (§5). The most eye-catching finding—the "used only once" claim—was reported and closed as Won't Fix, reinforcing that I had uncovered a documentation discrepancy rather than demonstrated a security vulnerability (§6).

Here are the implementation details I wish the docs had told me:

The authorization-code jti is BASE64URL(SHA-256(code)), while a refresh uses a random value. Different flows, different rules.
The first refresh triggers use_dpop_nonce before succeeding. You need a retry loop.
Mismatched htm/htu returns invalid_request, not invalid_dpop_proof.
iat acceptance spans 3600 seconds into the past and 10 seconds into the future. Clock skew toward the future can break every proof.
In a Node.js process, extractable: false isn't compatible with exporting a key for persistent storage. Plan key persistence first.
Verify refresh works without DPoP before adding DPoP; otherwise, proof errors can be hidden behind invalid_grant.

References

DPoP Adoption Guide — Google's DPoP implementation guide; proof construction and nonce handling.
Using OAuth 2.0 for Web Server Applications — Token endpoint parameters, error codes, and notes on prompt=consent.
OAuth 2.0 Best Practices — Recommendations on sender-constraining.
Announcing DPoP Support for Google OAuth — Google's announcement, performance trade-offs, and threat model.
RFC 9449 — DPoP specification; §5 token types, §10 dpop_jkt, §11 security considerations.
google/skills — dpop-adoption — Google's implementation skill; non-extractable keys and signature formats.

Why PHP Uses snake_case Functions but camelCase Methods

Hirohisa Tanaka — Thu, 13 Aug 2026 04:58:14 +0000

Built-in functions are usually snake_case.
Modern framework code is usually camelCase.

That is PHP: a language where naming conventions can feel oddly split.

So which naming convention is actually "correct" in PHP?

I'm tanahiro2010, and this is one of those small-but-persistent questions that keeps coming back whenever I write PHP.

Let me say this up front: this article is not about declaring either camelCase or snake_case the one true style. Instead, it looks at why PHP's naming conventions appear to differ by layer, traces that split through PHP's history, and offers a practical way to decide how to name things in your own code.

While writing this, I tried not to rely only on memory or second-hand explanations. Where possible, I checked primary sources such as the official PHP manual, the PHP-FIG website, and the PEAR manual. For historical details I could not fully verify, especially around early PHP-FIG membership and some framework-specific context, I explicitly mark them as unconfirmed or inferential.

A note on terminology
This article includes a few terms that may be unfamiliar if you are new to PHP or web development. When that happens, I add a short explanation in a blockquote like this. You can skip these blocks if you already know the terms; the main argument should still be readable without them.

Have you seen code like this?

When writing PHP, you often run into functions like these:

str_replace($search, $replace, $subject);
array_map($callback, $items);
json_encode($payload);
file_get_contents($path);

As you can see, these names use snake_case: words connected with underscores.

But modern PHP code, especially framework-based code, often looks more like this:

$request->getParsedBody();
$response->getStatusCode();
$userRepository->findById($id);

This time, the names use camelCase: words joined together, with later words starting with uppercase letters.

Inside the same language, PHP, two very different-looking styles coexist. This article traces where that split came from.

The conclusion first
Why PHP built-in functions look like snake_case
PHP 3 and the spread of function-based web programming
PEAR: shared conventions before PSR
PHP 5 and the rise of OOP PHP
Framework culture in the late 2000s
A side note on Symfony helpers
PHP-FIG and PSR
What PSR-1 says, and what it does not say
Why naming still hurts
Practical guidelines for modern PHP
Summary

1. The conclusion first

Before getting into the history, here is the conclusion of this article:

Regular functions, including global functions, helper functions, and procedural APIs: snake_case
Class methods: camelCase

After looking through PHP's history, this feels like the most natural compromise to me.

That said, this is not an absolute law. Always prioritize the following when they apply:

If an existing project already has a convention, follow it.
If your framework has a convention, such as Laravel, Symfony, or WordPress, follow it.
If you are naming a public API, preserving backward compatibility matters more than stylistic purity.

What is PSR?
PSR stands for PHP Standard Recommendation. PSRs are standards created by PHP-FIG, a group that defines coding styles and shared interfaces for the PHP ecosystem. PSR-1 and PSR-12 are examples. PSRs are not part of the PHP language specification itself; they are community standards.

One important premise: PHP does not enforce naming style at the syntax level. Whether you write names in snake_case, camelCase, or something else, the PHP interpreter will usually run the code just fine. In other words, PHP lets you write code that works even if it ignores naming conventions. This becomes important later when we talk about why naming still causes pain.

So why does "functions use snake_case, methods use camelCase" feel natural in PHP? Let's go back to 1995.

2. Why PHP built-in functions look like snake_case

PHP did not begin as a carefully designed language

PHP began as a small set of CGI binaries written by Rasmus Lerdorf in 1994 to track visits to his online resume. It was called "Personal Home Page Tools" or "PHP Tools". The source code was released in June 1995 (PHP: History of PHP - Manual).

What is CGI?
CGI stands for Common Gateway Interface. It is a mechanism that lets a web server call an external program and return the program's output to the browser. In the 1990s, CGI programs written in languages like Perl were a common way to generate dynamic web pages. PHP started in this world as a set of C-based executables.

In September 1995, PHP evolved into "FI" or "Forms Interpreter". In April 1996, the two were combined as "PHP/FI". Then in 1997, Andi Gutmans and Zeev Suraski, who were in Tel Aviv at the time, rewrote the parser and worked with Rasmus Lerdorf to create a new language. In June 1998, PHP 3 was released as the official successor to PHP/FI 2.0. The name also changed to the recursive acronym "PHP: Hypertext Preprocessor" (PHP: History of PHP - Manual).

In other words, PHP was not born from the sequence "design a complete language specification, then implement it." It grew from practical personal tools into a language because people needed it. Nobody was designing API naming conventions in anticipation of a massive global ecosystem thirty years later. That is the first point to keep in mind.

A function culture grew from there

Useful web development features, such as string handling, array operations, file operations, and database access, were added as functions.

Many functions that still exist in PHP today are part of that lineage:

str_replace();
array_map();
json_encode();
file_get_contents();
mb_strlen();
mysqli_connect();
array_filter();
preg_match();
htmlspecialchars();

As you can see, many of them use snake_case.

A technical note: why snake_case was likely natural

PHP's implementation is written in C. The core runtime is called the Zend Engine.

What is the Zend Engine?
The Zend Engine is the internal engine that parses and executes PHP code. It was developed by Andi Gutmans and Zeev Suraski and has been the execution foundation of PHP since PHP 3.

In C and its standard library ecosystem, function names are traditionally lowercase and often use underscores, although not always. Examples include names such as strcpy, memcpy, and time. Many early PHP built-in functions were thin wrappers around C functions or C libraries, so it is reasonable to think that C naming culture influenced PHP's function names.

I do not mean this as a claim that every PHP function directly follows C naming rules. I have not exhaustively verified that. It is better understood as a general tendency.

But it is not completely consistent

If the story ended here, we might say "PHP built-ins are all snake_case." But that would not be accurate. Standard classes in PHP often have camelCase or PascalCase-style method names:

$reflectionClass->getName();
$reflectionMethod->getParameters();
$dateTime->setTimezone($timezone);

What is Reflection?
ReflectionClass and ReflectionMethod are part of PHP's built-in Reflection API. Reflection lets a program inspect information about classes, methods, parameters, modifiers, and more at runtime. Frameworks and testing tools often use it internally.

So we need to distinguish between "global function culture" and "standard class/method culture". That difference connects directly to the later spread of object-oriented PHP.

What is OOP?
OOP stands for object-oriented programming. It is a way of designing programs around classes, where data and behavior are grouped together as properties and methods. The idea that "class methods use camelCase" comes up repeatedly later in this article.

The PHP manual also has a page called Userland Naming Guide. It states that function names should use underscores between words, and that both camelCase and PascalCase appear in class names. It also names strpos() as an example of an old naming mistake because it does not follow the recommended extension prefix rule.

So if PHP naming feels inconsistent, you are not imagining it. The official manual itself acknowledges historical inconsistency.

My summary for this section is: PHP's built-in functions look snake_case not because of a perfectly planned language design, but because early PHP grew out of practical C-based implementation culture.

3. PHP 3 and the spread of function-based web programming

PHP 3 was released in June 1998 as the official successor to PHP/FI. Around this point, PHP development expanded from a personal project into a broader multi-person effort. Features were added rapidly through extension modules.

What is an extension module?
An extension adds functionality to PHP itself. For example, the curl extension provides HTTP communication through the cURL library, and the mysqli extension provides MySQL access. Many PHP built-in functions are grouped by extensions like these.

During this period, practical web development needs such as database access, form handling, and session management drove PHP's growth. Functions were added as needed. There was not yet a strong centralized process for reviewing naming consistency. Functionality and usefulness came first; naming consistency came later, if at all.

Once a name is public, changing it is hard

Once a function name is public and widely used, it becomes difficult to change. This is a backward compatibility problem.

What is backward compatibility?
Backward compatibility, often abbreviated BC, means code written for an older version of software keeps working in newer versions. Renaming or removing a function can break every existing codebase that uses it, so many languages and frameworks treat public API names as something that should not be changed casually.

PHP's old mysql_* functions, such as mysql_query, are a good example. They went through deprecation and were eventually removed, but that took a long time. This illustrates how hard it is to change names and APIs after they become widely used. I am keeping this example at a high level here because I did not fully verify the detailed year-by-year timeline for this article.

Naming is not decided by philosophy alone

So far, we can see that naming depends on several axes:

Axis	Example
When it was created	Pre-2000 PHP built-ins vs post-PSR code
Who created it	Rasmus Lerdorf individually vs a group such as PHP-FIG
Which culture it came from	C-style function culture vs OOP framework culture
Whether compatibility can be broken	Global functions with huge compatibility cost vs new framework APIs
Which API layer it belongs to	Built-in language functions vs userland classes

It is easy to say PHP naming is inconsistent because the design philosophy was inconsistent. But in practice, PHP's naming style is the result of several historical layers overlapping.

4. PEAR: shared conventions before PSR

What is PEAR?

Before PSR, PHP already had shared coding conventions. They came from PEAR.

What is PEAR?
PEAR stands for PHP Extension and Application Repository. It is a repository and package distribution system for reusable PHP libraries.

One fact-checking note: in an earlier draft, I wrote that PEAR was released in December 2002. After checking multiple sources, I found that PEAR was started around 1999 by Stig Bakken. It is said to have grown out of discussions at the PHP Developers' Meeting in Tel Aviv in January 2000. I could not find a primary source confirming the 2002 date, so this article treats PEAR as a project that began around 1999. I have not pinned down the exact founding date or release timeline.

PEAR naming conventions

PEAR had clear naming conventions more than a decade before PSR (PEAR Manual: Naming Conventions).

Target	Rule	Example
Class names	Initial uppercase, hierarchy expressed with underscores	`Log`, `Net_Finger`, `HTML_Upload_Error`
Method names	Lowercase first word, then studly caps	`connect()`, `getData()`, `buildSomeWidget()`
Global functions	Package name prefix, then studly caps	`XML_RPC_serializeData()`
Constants	Uppercase with underscores	`DB_DATASOURCENAME`, `SERVICES_AMAZON_S3_LICENSEKEY`

The interesting part is that PEAR recommended a camel-like style even for global functions. So the simple story "PHP functions have always been snake_case" is not quite true. Even before PSR, there was already a separate naming culture inside the PHP community that differed from PHP built-in function style.

PEAR class names as pseudo-namespaces

Class names such as Net_Finger and HTML_Upload_Error may look strange today, but they had a technical reason.

What is a namespace?
A namespace is a way to prevent name collisions by giving classes and functions a kind of address. PHP introduced the namespace keyword in PHP 5.3 in 2009. Before that, PHP did not have native namespaces.

In the PEAR era, PHP did not have namespaces, so libraries avoided class-name collisions by encoding hierarchy in the class name itself: package name, underscore, class name. Today you might write Net\Finger; back then, Net_Finger served a similar purpose through naming convention alone.

What this section tells us

The important point is that the "built-in function layer" and the "library distribution layer" belonged to different cultures.

Also, my conclusion in this article, "regular functions use snake_case", does not come from PEAR. PEAR actually recommended camel-like global function names. My conclusion comes from PHP's built-in function culture and practical modern PHP context, not directly from PEAR.

5. PHP 5 and the rise of OOP PHP

What Zend Engine 2.0 changed

PHP 5 was released in July 2004. It introduced Zend Engine 2.0 and a new object model (PHP: History of PHP - Manual). The biggest technical change was how objects behaved.

In PHP 4, passing or assigning objects could internally copy them.
In PHP 5, objects were handled through handles, closer to references in many object-oriented languages.
Access modifiers such as private, protected, and public were introduced.
interface and abstract class were introduced.
Magic methods such as __construct and __destruct were clarified.

What are magic methods?
Magic methods are special methods that begin with two underscores, such as __construct(). PHP calls them automatically at specific moments, such as when an object is created.

These changes made PHP a language where serious class design became practical. This became the foundation for object-oriented PHP culture.

From calling functions to writing methods

The look of PHP code also started changing around this period.

// PHP 4-ish: calling functions
array_map($callback, $items);
json_encode($payload);

// PHP 5 and later: writing methods
$request->getParsedBody();
$response->getStatusCode();

Method names such as getParsedBody(), getStatusCode(), findById(), setCreatedAt(), hasPermission(), and isPublished() became common. The get / set / is / has patterns are common not only in PHP, but also in many object-oriented programming communities.

PHP 5 is where PHP really started to develop a culture of thinking about names at the method level.

6. Framework culture in the late 2000s

Frameworks that adopted camelCase methods

After PHP 5, frameworks and libraries such as CakePHP, Symfony, Zend Framework, Doctrine, and CodeIgniter appeared and grew.

Here is a rough summary of their method naming tendencies, based on what I was able to check. This is not an exhaustive verification of every version or module.

Project	Type	Method naming tendency	General character
CakePHP	Full-stack framework	camelCase	Convention-over-configuration MVC framework
Symfony	Full-stack framework	camelCase	OOP-oriented components and framework
Zend Framework	Framework / library collection	camelCase	Enterprise-oriented design
Doctrine	ORM library	camelCase	Maps database tables to objects
CodeIgniter	Lightweight framework	More snake_case-oriented	Simplicity closer to procedural PHP

What is an ORM?
ORM stands for Object-Relational Mapping. It maps database tables to program objects. Doctrine is one of the best-known ORM libraries in PHP.

As this table suggests, many major frameworks except CodeIgniter leaned toward camelCase method names. CodeIgniter is an important counterexample: not everything in that era was camelCase. It kept a style closer to procedural PHP and PHP's built-in function culture. I could not fully verify an official primary-source statement for that design intent, so I am treating it as a broad tendency rather than a definitive claim.

From here on, some of this is circumstantial

Next comes the question: why did PSR-1 choose camelCase for methods?

To be honest, I could not find a primary source that directly explains the reasoning behind that choice. So from here, I am presenting a hypothesis based on circumstantial evidence.

Hypothesis: camelCase culture was already widespread

My hypothesis is this:

PSR-1 did not introduce camelCase to PHP from nowhere. Instead, it formalized and stabilized a camelCase culture that had already spread through object-oriented PHP frameworks by the late 2000s.

To support that hypothesis, we need to look at PHP-FIG.

7. A side note on Symfony helpers

Symfony 1.x code and documentation reveal an interesting detail. In the Symfony 1.x coding standards, class names and variable names were generally expected to use UpperCamelCase, also called PascalCase, but there were two exceptions: core classes prefixed with lowercase sf, such as sfController and sfRequest, and template variables, which used underscore-separated notation (Symfony 1.4 legacy documentation: Exploring Symfony's Code).

I want to be careful here. In an earlier draft, I had written a more specific anecdote: that the Symfony documentation explained helper functions were not camelCase because helpers were functions, and therefore followed PHP core functions. When I rechecked primary sources, I could not confirm that specific Q&A-style explanation. What I did find was the documented rule about underscore notation for template variables.

So I will avoid stating that helper explanation as fact.

Still, the verified fact is useful: Symfony 1.x mostly used camelCase/PascalCase conventions for classes and variables, while some areas followed different conventions. This shows that two cultures coexisted even within the same framework:

a procedural, PHP-built-in-function-like culture
an OOP framework, camelCase-oriented culture

That coexistence supports the way this article separates functions and methods.

8. PHP-FIG and PSR

What is PHP-FIG?

The group behind PSRs is PHP-FIG.

What is PHP-FIG?
PHP-FIG stands for PHP Framework Interop Group. It is a group created by PHP framework developers to improve interoperability across the PHP ecosystem.

According to the official PHP-FIG FAQ, the group was formed in 2009 at the php|tek conference by several framework developers. It started with around five members and later grew through a voting process to include more than twenty member projects (PHP-FIG FAQ).

What is php|tek?
php|tek is a conference for the PHP community.

Here is another fact-checking note. In an earlier draft, I listed specific founding members and associated projects, such as Matthew Weier O'Phinney for Zend Framework, Fabien Potencier for Symfony, Paul M. Jones for Solar/Aura, Jonathan Wage for Doctrine, and Nate Abele for Lithium. However, I could not find a primary source on the PHP-FIG website that explicitly identifies the original five people.

After additional research, I found a retrospective explanation by a participant on the early php.standards mailing list. It says that the group that became PHP-FIG included representatives from projects such as Agavi, CakePHP, PEAR, Phing, Solar, Symfony, and Zend Framework.

Combining that information with individual profiles and project histories, such as official Zend/Laminas pages and interviews, gives us this rough argument:

People associated with early PHP-FIG were involved in these projects.
Many of those projects already leaned toward camelCase method names.
Therefore, the early PHP-FIG ecosystem was already strongly connected to camelCase-oriented OOP PHP culture.

Person	Project associated at the time	Method naming tendency
Matthew Weier O'Phinney	Zend Framework	camelCase
Paul M. Jones	Solar	camelCase
Nate Abele	CakePHP at the time, later Lithium	camelCase
Fabien Potencier	Symfony	camelCase
Representative names not fully confirmed	PEAR / Phing / Agavi	PEAR recommended camel-like global functions; Phing and Agavi not verified here

Two cautions:

First, this is not a definitive mapping of the original five founding members in 2009. It is a combination of early project names and people known to be associated with them.

Second, I removed the Jonathan Wage / Doctrine pairing from the table because I could not verify it from primary sources during this research.

Even with those cautions, the evidence I could confirm still supports the idea that early PHP-FIG was surrounded by projects where camelCase methods were already common.

Interoperability was the keyword

PHP-FIG's goal was interoperability.

What is interoperability?
Interoperability is the ability of different software systems to work together. In PHP-FIG's context, it means code written for one framework should be easier to combine with code from another framework.

The goal was to make shared PHP code, cross-framework libraries, and reusable components easier to mix together. One of the first topics PHP-FIG worked on was coding style, which later became PSR-1 and PSR-12.

PHP-FIG has produced many standards beyond naming and formatting. PSR-3 defines a logging interface, PSR-4 defines an autoloading standard, and PSR-7 defines common HTTP message interfaces. PHP-FIG is not only about coding style; it is about interoperability across the PHP ecosystem.

9. What PSR-1 says, and what it does not say

The purpose of PSR-1

PSR-1, formally called "Basic Coding Standard", describes its purpose like this (PSR-1: Basic Coding Standard):

This section of the standard comprises what should be considered the standard coding elements that are required to ensure a high level of technical interoperability between shared PHP code.

In other words, PSR-1 defines basic coding elements needed for shared PHP code to interoperate well.

What PSR-1 defines

PSR-1 defines the following naming conventions:

Target	Rule
Class names	`StudlyCaps`
Class constants	`UPPER_CASE_WITH_UNDERSCORES`
Method names	`camelCase()`

What is StudlyCaps?
StudlyCaps means writing words together with each word starting with an uppercase letter. It is roughly equivalent to what many people call PascalCase, for example HttpClient.

For property names, PSR-1 does not require one specific convention. It says $StudlyCaps, $camelCase, and $under_score are all acceptable, but whichever convention is used should be applied consistently within a reasonable scope.

PSR-12, "Extended Coding Style", adds more detailed rules for indentation, line breaks, class and method declarations, control structures, and so on. But it does not add a new rule such as "variables must be camelCase."

What PSR-1 does not define

This distinction is the most important point for this article. PSR-1 does not define naming rules for:

regular global functions
variable names
existing PHP built-in functions

So the claim "Because PSR exists, PHP functions should be camelCase" does not follow from PSR-1 itself.

Why built-in functions do not look like PSR

The reason is simple: many built-in functions existed long before PSR. Renaming them now would break backward compatibility. Also, PSR-1 was never meant to impose naming rules on PHP's built-in functions.

Why PSR does not look like built-in functions

This part cannot be proven definitively from the sources I found. But based on the evidence from sections 6, 7, and 8, I think the most natural reading is:

PSR-1 did not invent camelCase from scratch. It formalized the camelCase method culture already common in userland OOP frameworks at the time.

As a side note, PSR-1 has a Meta Document that lists Paul M. Jones as an editor (PSR-1 Meta Document). According to Paul M. Jones's own blog post from June 4, 2012, PSR-1 and PSR-2 were accepted by vote, with PSR-1 passing 17 to 0 (Paul M. Jones: PHP-FIG: PSR-1 and PSR-2 Accepted).

In an earlier draft, I wrote that PSR-1 was released on June 5, 2012. The primary source I confirmed is the June 4, 2012 blog report, and I could not confirm the exact vote closing date. So this article uses the more cautious phrasing "accepted in early June 2012." It is also more accurate to say "PHP-FIG created PSR-1, and Paul M. Jones was one of its editors" than to say simply "Paul M. Jones created PSR-1."

10. Why naming still hurts

PHP does not enforce naming conventions at the syntax level. Variables, functions, and methods can be snake_case, camelCase, PascalCase, or something else, and PHP will usually run the code.

This has both benefits and costs.

Benefit: Beginners can start writing PHP without worrying about naming rules, which lowers the learning barrier.
Cost: Once code is written by a team, naming inconsistencies become visible in code review and hurt readability.

Personally, I have often been confused by code whose naming style was mixed, especially code written without knowledge of PHP's history or PSR, including code I wrote myself in the past.

I do not think this means the original author was bad. It is a consequence of PHP itself: you can write working code without knowing the conventions.

That is why it helps to know the history and then decide what your own project should do.

11. Practical guidelines for modern PHP

Based on the history above, here are the factors I would consider in real projects:

PHP built-in function culture
OOP culture
PSR rules
project consistency
framework conventions
public API compatibility

Common arguments from both sides

In practice, this debate usually produces arguments like these. Both sides have reasonable points. This article is not trying to prove one style superior to the other.

Camp	Common argument
snake_case	Matches PHP built-in functions; word boundaries are visually clear; less worry about uppercase/lowercase typos
camelCase	Matches PSR-1 for methods; aligns with OOP culture in Java, JavaScript, C#, and others; fits major framework conventions

My position is that we can reconcile both sides by separating the layer: inside classes or outside classes.

Here is the concrete recommendation:

Use snake_case for global functions, helper functions, and procedural APIs.
- Reason: This aligns with PHP's built-in function culture and keeps procedural code visually consistent with the standard library.
Use camelCase for class methods.
- Reason: This follows OOP PHP culture and PSR-1.
For properties and variables, PSR-1 does not prescribe one rule, so prioritize consistency within the relevant scope.

And again, always prioritize these rules when they apply:

If a project already consistently uses snake_case methods, follow that project.
Respect the conventions of the surrounding ecosystem, such as Laravel, Symfony, or WordPress.
For public APIs, preserving backward compatibility comes first.

Before and after

Suppose you have a class with mixed naming:

// Before: inconsistent method names
class UserRepository
{
    public function find_by_id($id) { /* ... */ }
    public function GetAll() { /* ... */ }
    public function delete_user($id) { /* ... */ }
}

Applying this article's guideline, class methods become camelCase:

// After: methods unified as camelCase
class UserRepository
{
    public function findById($id) { /* ... */ }
    public function getAll() { /* ... */ }
    public function deleteUser($id) { /* ... */ }
}

But helper functions outside a class remain snake_case:

// Plain helper functions outside classes stay snake_case
function format_currency($amount) { /* ... */ }

The practical rule is: separate by whether the name belongs inside a class or outside one.

Here is the decision flow:

flowchart TD
    A[You need to choose a name] --> B{Does the project already have a convention?}
    B -->|Yes| C[Follow it]
    B -->|No| D{Does the framework have a convention?}
    D -->|Yes| C
    D -->|No| E{Is it a class method?}
    E -->|Yes| F[camelCase]
    E -->|No| G{Is it a global function or helper?}
    G -->|Yes| H[snake_case]
    G -->|No| I[Other cases: prioritize consistency within scope]

These conventions can also be checked mechanically instead of relying only on human review.

What is static analysis?
Static analysis means analyzing source code without running it, usually to detect possible bugs, type issues, or style violations. In PHP, PHPStan is one of the most widely used static analysis tools.

Tools such as PHP_CodeSniffer, which can detect and automatically fix coding style violations, and PHPStan, which performs static analysis, can help teams enforce PSR-1/PSR-12 and other style rules consistently.

12. Summary

To summarize:

PHP naming conventions are not one single unified system.
PHP built-in function culture, PEAR/library culture, OOP framework culture, and PSR culture exist as historical layers.
Looking at that history, "functions use snake_case, methods use camelCase" feels like a natural practical guideline.
But it is not an absolute rule. Existing project conventions, framework conventions, and backward compatibility always come first.

I was never especially good at history classes in school, but researching PHP's history was genuinely fun. If this article made you a little more curious, I would be happy. And if it makes you want to dig into the later history of PSR-2 to PSR-12, or the changes brought by PHP 7 and PHP 8, that would be even better.

References

If You Can Give a Lightning Talk, You Can Probably Go Bungee Jumping

Hirohisa Tanaka — Sat, 08 Aug 2026 12:42:03 +0000

If You Can Give a Lightning Talk, You Can Probably Go Bungee Jumping

I have a question for anyone who has ever given a lightning talk.

Do you remember those few dozen seconds right before you walked on stage?

Do you remember what was happening to your body?

I do.

In fact, this article itself started as something I talked about during a lightning talk. And while I was speaking, a strange thought suddenly popped into my head:

“Wait. Aren’t lightning talks kind of like bungee jumping?”

Written down like that, it sounds like an absurd claim.

I know.

But at least in my own experience, the excitement I feel right before stepping onto a stage is surprisingly similar to what I feel when standing on a bungee platform and looking down.

So in this article, I want to develop the ridiculous-sounding claim in the title — “If you can give a lightning talk, you can probably go bungee jumping” — while keeping the casual spirit of the original idea and giving it at least some concrete reasoning.

If, by the end of this article, the thought “Bungee jumping sounds kind of interesting” appears in your head before “Lightning talks are scary,” then this article has accomplished its mission.

The Nervousness Before a Lightning Talk and the Fear Before a Bungee Jump

That restless feeling right before a lightning talk is probably nervousness.

The similar feeling right before a bungee jump is probably fear.

Strictly speaking, these are different emotions.

Nervousness comes from uncertainty: Can I do this well?

Fear comes from perceived danger: Am I safe?

Their causes are completely different.

But if we move one level higher and look at what the body actually does, the two experiences start looking surprisingly similar.

Your heart rate increases.

Your palms get a little sweaty.

Your breathing becomes shallow.

You cannot quite settle down.

And somehow, two contradictory thoughts exist at the same time:

“I want to escape.”

and

“I still want to do this.”

More importantly, the peak of that reaction happens before the experience actually begins.

With a lightning talk, the most nerve-racking moment is often right before stepping onto the stage, or just before opening your slides and saying the first sentence.

Once you actually start talking, the nervousness tends to drop very quickly.

Bungee jumping feels similar.

Standing on the platform, having the equipment checked, and finally looking down is the scariest part.

Once you jump, fear is no longer the only thing occupying your brain.

There is another similarity too: once the experience begins, your body almost seems to take over.

Once you start a lightning talk, your main remaining option is to keep talking.

Once you jump off a bungee platform, continuing to fall is no longer exactly optional.

That structure — the moment where starting removes most of your ways to back out — might be one of the biggest reasons why the two experiences feel so similar to me.

`===` Is False, but `==` Might Be True

Obviously, a lightning talk and bungee jumping are completely different activities.

A lightning talk is an intellectual activity where you share ideas with an audience.

Bungee jumping involves physically falling from a very high place while attached to a cord.

The actions are different.

The skills involved are different.

The risks are definitely different.

If we borrow a programming metaphor:

lightningTalk === bungeeJumping
// false

Strict equality does not hold.

But what if we narrow the comparison?

What if we only compare these three things?

The emotional peak happens before starting.
Once it starts, time feels extremely short.
After it ends, you somehow want to do it again.

Under those conditions, at least in my head:

lightningTalk == bungeeJumping
// surprisingly true

If we allow a little type coercion, they start looking oddly equivalent.

But if we require both the type and value to match exactly, of course they are not.

That is roughly the level of seriousness with which this entire article should be read.

Comparing Lightning Talks and Bungee Jumping

To make the argument slightly more structured, here is a direct comparison.

Perspective	Lightning Talk	Bungee Jumping
Before it starts	Nervousness reaches its peak	Fear reaches its peak
After it starts	Time feels extremely short	Time feels extremely short
After it ends	You want to speak again	You want to jump again

The first similarity is that the emotional peak happens before the activity begins.

For a lightning talk, it happens right before going on stage.

For a bungee jump, it happens when you are standing on the platform and looking down.

In my experience, the anxiety or fear rarely gets stronger after starting.

The second similarity is how short the experience feels once it begins.

Lightning talks are usually around five to ten minutes long, and once you start speaking, they tend to end much faster than expected.

A bungee jump is even shorter.

The period between jumping and reaching the end of the fall is only a matter of seconds, and subjectively it feels even shorter.

The third similarity is that immediately afterward, you want to do it again.

After a lightning talk, I often find myself thinking:

“What should I talk about next?”

After bungee jumping, strangely enough, I get a similar feeling:

“I kind of want to jump again.”

This is entirely based on my own experience.

I have no scientific evidence that everyone reacts this way.

But at least for me, it happens almost every time.

What About Other Types of Public Speaking?

At this point, there is an obvious question.

If public speaking in general feels similar to bungee jumping, why specifically talk about lightning talks?

My answer is that not every kind of speaking feels the same.

The speaking activities I have personally experienced can roughly be divided into three categories:

Lightning talks
Regular conference or seminar talks
Hands-on workshop instruction

Out of these, lightning talks feel the most like bungee jumping.

A normal conference or seminar presentation tends to be much longer.

It might last thirty minutes, an hour, or sometimes even longer.

When you speak for that long, the nervousness gradually fades during the presentation. At some point, it starts feeling almost routine.

That is not a bad thing.

Preparing a longer presentation forces you to research the topic more deeply.

The research itself often improves your understanding as an engineer.

Questions from the audience and the preparation process can also expose gaps in your own knowledge.

Those are all valuable things.

But on the specific axis of “How similar is this to bungee jumping?”, they do not matter very much.

A long presentation feels less like jumping and more like walking a long distance until you finally reach the destination.

Hands-on workshops are even more different.

During a workshop, teaching is only part of the job.

You also deal with:

Differences between participants’ environments
Mysterious errors
Dependencies that refuse to install
Sample code that suddenly stops working
Problems that somehow only happen on one person’s machine

I enjoy that too.

But once a workshop begins, the dominant feeling is not “I’m jumping.”

It is closer to:

“I am operating a live system.”

So among the kinds of speaking I have experienced, lightning talks still feel the most similar to bungee jumping.

They are short.

The emotional peak happens right before the start.

And after they end, you often want to do them again.

The Scariest Part Is Before the Jump

There is an obvious response to everything I have written so far:

“Bungee jumping is scary.”

Yes.

It is.

I am not going to pretend otherwise.

But for me, most of that fear is concentrated before the jump.

You stand on the platform.

You look down.

You suddenly understand exactly how high you are.

That moment is genuinely scary.

But once you actually jump, the experience becomes surprisingly short.

The falling sensation is somewhat similar to the drop on a roller coaster.

There is definitely excitement after the jump begins, but the highest concentration of emotion exists in the moments before it.

Lightning talks work in a similar way.

The strongest nervousness usually happens before the talk.

After it ends, instead of thinking only about how stressful it was, I naturally start wondering what I should speak about next.

The important point is not that fear or nervousness disappears.

It is understanding where the peak actually happens.

And in both experiences, the peak comes before the beginning.

Commitment Makes Backing Out Harder

There is one more major similarity between lightning talks and bungee jumping.

Making a commitment in advance makes it harder to back out later.

Before submitting a lightning talk proposal, you can keep telling yourself:

“Maybe I’ll speak someday.”

There is no problem with that.

But once you submit the talk, something changes.

Your name is now attached to a future event.

You have accepted the role of “the person who is going to speak.”

That suddenly turns a vague idea into an actual commitment.

Now you have to make the slides.

You have to research the topic.

You have to prepare.

Bungee jumping has a similar structure.

Thinking:

“I want to try bungee jumping someday.”

can remain a vague idea forever.

But saying publicly:

“I’m going bungee jumping.”

makes the idea slightly more real.

Your psychological escape route gets a little narrower.

And personally, I find that process strangely entertaining.

Of course, this is not an argument for forcing people into things they genuinely cannot or do not want to do.

The idea is much lighter than that.

Sometimes, making a half-joking, half-serious commitment is enough to make your future self actually move.

Sign Up for a Lightning Talk So You Can Go Bungee Jumping

You might have reached this point thinking:

“Bungee jumping still sounds difficult, but maybe I could try a lightning talk.”

Unfortunately, that is not quite the order I am proposing.

I am suggesting that you give a lightning talk so that you can eventually go bungee jumping.

Submitting a lightning talk is a useful exercise in creating commitment.

It teaches you how to turn:

“Maybe someday.”

into:

“Okay. I guess I’m actually doing this.”

And compared with jumping off a tall platform, a five-minute talk is a relatively manageable first step.

That said, once you submit a lightning talk, another problem appears:

What do you actually do next?

Here is roughly how I prepare.

First, I research the topic as broadly as possible.

I look through official documentation, related articles, implementation examples, old notes, and anything else that seems remotely relevant.

At this stage, I intentionally avoid narrowing the scope too early.

Then I dump everything into a note-taking app or Markdown file.

I do not worry about structure.

I write bullet points.

I nest ideas.

I add random observations.

I leave things in even when I am not sure whether they will be useful later.

Once I have accumulated roughly ten thousand Japanese characters’ worth of material, I finally start thinking seriously about the structure of the talk.

Only then do I decide what to keep and what to remove.

For me, trying to create a clean structure from the beginning often causes the work to stall because I simply do not have enough raw material yet.

So instead, I prefer to collect too much information first and cut it down afterward.

I also find it useful to bounce ideas off AI tools.

Ideas that seem perfectly connected inside my own head often reveal logical gaps when I try to explain them to someone else.

Even when the conversation partner is an AI, questions such as:

“How strongly can you actually support that claim?”

“What should the audience take away from this?”

can force me to organize my thoughts much more clearly.

Okay, So Who Wants to Go Bungee Jumping?

So, after all of that, here is my conclusion:

If you can give a lightning talk, I think you can probably go bungee jumping too.

If we inspect the two activities strictly, there are obviously countless differences.

But if we only compare these three things:

The emotional peak happens before starting.
Once it starts, time feels extremely short.
After it ends, you somehow want to do it again.

Then I think lightning talks and bungee jumping are surprisingly similar experiences.

And perhaps the most important part is the act of commitment itself.

You make a decision in advance.

You slightly reduce the number of escape routes available to your future self.

And somewhere inside that situation, fear and excitement start existing at the same time.

So yes.

I recommend bungee jumping.

Half as a joke.

Half seriously.

Whether you actually jump is entirely up to you.

But if this article made you even slightly curious about it, feel free to reach out.

Maybe we should go jump together someday.

I Built a Bridge for Google's New WebMCP Draft Spec — Here's What Broke

Hirohisa Tanaka — Mon, 03 Aug 2026 10:22:51 +0000

Hi, everyone.
I usually go by tanahiro2010 in Japan.
I'm a member of GDG Greater Kwansai.
I gave the first-half talk at the Google I/O Extended Osaka 2026 hands-on session, "Let's Build WebMCP and Call It from an AI Agent!"
This is a write-up of that hands-on session for Qiita (translated here for Dev.to).
Here's the codelab we used:
https://learn.gdgs.jp/webmcp-agent/

This is for people who already know MCP but have never heard of WebMCP, and for people who want to know "so what's this new spec Google put out, actually like?"

Have you heard of WebMCP?

Let me just ask straight up: have you heard of WebMCP?
I hadn't even heard it existed until I started putting together the hands-on materials.
Just from the name, I assumed it was "the Web version of MCP."
But once I actually read the spec and implemented it, it turned out to be a much quirkier spec than I expected.
In this article I'll walk through what's actually in it, and what I learned by getting my hands dirty with it.

First, what is MCP?

Before getting into WebMCP, let's recap MCP (Model Context Protocol).
MCP is a common interface for connecting external tools to an AI Agent.
The flow looks like this:

sequenceDiagram
    participant Agent as AI Agent
    participant Server as MCP Server
    Agent->>Server: Launch (stdio / HTTP)
    Server-->>Agent: tools/list (list of available tools)
    Agent->>Server: tools/call (tool name + args)
    Server->>Server: Execute the tool
    Server-->>Agent: Return the result

The key point is that the tools stay registered for as long as the Agent is running.
Whether it's a local file operation or a tool that hits an internal API, you can keep calling it as long as you don't kill the Agent.
The webmcp-bridge-mcp I built for this is also just an ordinary MCP Server listening on stdio.
From the perspective of a client like the Antigravity CLI, it's nothing more than "one more run-of-the-mill MCP Server."
What's unusual is the WebMCP side, which I'll get to next.

What is WebMCP?

WebMCP is a draft spec published by the W3C Web Machine Learning Community Group.
https://webmachinelearning.github.io/webmcp/
As of writing, it's the February 2026 draft — still at the proposal stage.

In one sentence:

A mechanism by which a web page itself declares its own features as tools for an Agent.

There are two ways to register a tool.

Imperative

You register a tool directly from JavaScript.

await document.modelContext.registerTool({
  name: "reserve_hotel",
  description: "Reserve a hotel",
  inputSchema: {
    type: "object",
    properties: { city: { type: "string" } },
    required: ["city"],
  },
  execute: async ({ city }) => ({ ok: true, city }),
});

The shape — name / description / inputSchema / execute — is almost identical to an MCP tool definition.
Anyone who's touched MCP will look at this and immediately think, "oh, this is the same shape as that."

Declarative

You turn an existing <form> into a tool just by adding attributes to it.

<form toolname="search_hotels" tooldescription="Search hotels">
  <input name="city" toolparamdescription="City to search hotels in" required />
  <button type="submit">Search</button>
</form>

When a form with toolname / tooldescription is found, a JSON Schema is automatically assembled from each <input>'s name, required, and toolparamdescription (or, if that's absent, the text of the associated <label>).

Here's the interesting part: internally, the declarative form gets normalized into the same registerTool() call as the imperative form.
Rather than having two separate APIs, the declarative form is implemented as syntactic sugar over the imperative one.
Personally, I genuinely like this design.

The submission result is received via SubmitEvent#respondWith(), as specified.

form.addEventListener("submit", (event) => {
  event.preventDefault();
  if (event.agentInvoked) {
    event.respondWith(Promise.resolve({ ok: true /* ... */ }));
  }
});

event.agentInvoked lets you tell whether a human clicked the button or an Agent submitted the form.
It's a small detail, but it ends up mattering a lot later.

MCP and WebMCP: similar names, but...

Because the name and the shape of the API are so similar, my initial impression was roughly "it's just the Web version of MCP."
But once I actually dug in, they turned out to differ clearly along three axes.

Item	MCP	WebMCP
Target	AI Agents in general	Per the spec, mainly browser-embedded Agents
Registration timing	Once, at Agent startup	Every time the page is opened
Session lifetime	Until the Agent is terminated	Only while the page is open
Execution location	Local or a service server	Inside that browser, on that page

The difference I felt most viscerally was the session lifetime.

stateDiagram-v2
    [*] --> Unavailable
    Unavailable --> Available: Open the tab
    Available --> Unavailable: Close/leave the tab
    Unavailable --> Available: Return to the tab

An MCP tool can be called as long as the Agent is up and running.
But a WebMCP tool is completely tied to "whether that page is currently open."
The moment you switch tabs, that tool disappears from view; go back, and it reappears.
The idea that "the tab's lifetime = the tool's lifetime" felt pretty fresh to someone coming from an MCP-only mindset.

How much of it actually works, as of August 2026

As of this writing (August 2026), WebMCP is still a draft at the proposal stage.
Even Chrome's own docs introduce it as an "upcoming feature."
https://developer.chrome.com/docs/ai/webmcp?hl=ja

You can join the Origin Trial starting with Chrome 149
To just try it locally, use chrome://flags/#enable-webmcp-testing
It's explicitly noted that the API may still change

In other words, you can't assume "the native implementation is enabled in every attendee's browser at the hands-on venue."
This is where the thing I built comes in.

What I built — WebMCP Bridge

There was a genuine gap between the hands-on requirements and the WebMCP spec if you approached it head-on.

What the spec assumes: WebMCP is for browser-embedded Agents
The reality of the hands-on: participants wanted to call it from an existing MCP-capable Agent, like the Antigravity CLI

So, I decided to build something to bridge the two.
With that in mind, I built a Chrome Extension and an MCP Server as a set.

MCP Server: https://github.com/tanahiro2010/webmcp-bridge-mcp
Chrome Extension: https://github.com/tanahiro2010/webmcp-bridge-extension

There's one thing I was particular about here:

Only detect and execute the APIs defined by the WebMCP spec (document.modelContext / annotated <form>s) as-is.

I didn't want to override the spec with some custom protocol of my own.
The reason is simple: if what people learn in the spec and what actually runs end up diverging, there's no point in running the hands-on in the first place.

Overview of the Bridge

Here's the overall structure:

flowchart LR
    Agent["AI Agent<br>(e.g. Antigravity CLI)"]
    MCP["webmcp-bridge-mcp<br>(MCP Server)"]
    Ext["webmcp-bridge-extension<br>(Chrome Extension)"]
    Page["Web page<br>(WebMCP-enabled)"]
    Agent <-->|stdio, MCP| MCP
    MCP <-->|WebSocket| Ext
    Ext <-->|content/injected script| Page

The MCP Server (webmcp-bridge-mcp) never touches the DOM directly itself.
It sticks strictly to being a Bridge / Registry / Router between itself and the Extension, and leaves all DOM manipulation to the Extension side.
It's a fairly unglamorous division of labor, but the responsibilities are clear, and I had few doubts while implementing it.

The WebSocket binds to ws://127.0.0.1:58787.
I used 58787 instead of 8787 because 8787 collided with the default port for wrangler dev (Cloudflare Workers).
When I had Workers development running in parallel, the Extension would end up connecting to wrangler instead of my server, and I'd sit there wondering why nothing would connect — a fairly unglamorous bug I ran into early on.

The Extension side is MV3-based and has a two-layer structure.

flowchart TB
    subgraph Page["Inside the web page"]
        direction TB
        Injected["injected.ts<br>(main world)"]
        Content["content.ts<br>(isolated world)"]
        Injected <-->|postMessage| Content
    end
    Background["background.ts<br>(Service Worker)"]
    WS["MCP Server"]
    Content <-->|chrome.runtime| Background
    Background <-->|WebSocket| WS

The reason injected.ts needs to run in the main world is that accessing the page's document.modelContext requires running in the main world.
You can't touch it directly from the isolated world (a normal content script).
When document.modelContext isn't yet natively implemented in the browser, injected.ts provides a minimal polyfill for registerTool / getTools / executeTool / the toolchange event.
If a native implementation exists, it does nothing.
By designing it as "quietly defer if a native implementation exists," I expect I won't need major code changes even as native implementations roll out.

Tools visible to the Agent

There are six tools visible to the Agent:

Tool	Description
`webmcp_get_status`	Returns the Extension's connection state, number of known tabs, and the active tab ID
`webmcp_list_tabs`	Returns the list of WebMCP-enabled tabs the Extension has captured
`webmcp_discover_tools`	Discovers the WebMCP tools on a given tab
`webmcp_call_tool`	Executes a tool on a given tab
`webmcp_submit_tool`	Confirms a submission that's waiting on a human, from the Agent side
`webmcp_ping`	Checks connectivity with the Extension

Here's what the input/output look like:

// webmcp_discover_tools input
{ "tabId": 123, "forceRefresh": true }
// output
{ "tabId": 123, "tools": [ { "id": "reserve_hotel", "name": "reserve_hotel", "source": "imperative" } ] }

// webmcp_call_tool input
{ "toolId": "reserve_hotel", "args": { "city": "Osaka" } }
// output
{ "ok": true, "result": { "ok": true, "city": "Osaka", "confirmationId": "RES-12345" } }

webmcp_submit_tool is a bit unusual.
Per the spec, a declarative form without toolautosubmit is expected to stop by focusing the submit button, so that a human reviews the content and submits manually.
This is a safety mechanism intentionally built into the WebMCP spec.
webmcp_submit_tool is a tool for explicitly overriding that from the Agent side.
I've written a note in the README that this should only be used with the understanding that it bypasses the human confirmation the spec intends.

Running it on real hardware, it was riddled with landmines

This is the part I most wanted to write about in this article.
Things I never would have noticed just from reading the docs kept popping up once I actually ran it on Chrome for Testing.

`getTools()` turned out to be async

From skimming the summary in Chrome's developer docs, my impression was that it was a synchronous function.
But when I checked on real hardware (Chrome for Testing 150), document.modelContext.getTools() returned a Promise<ModelContextTool[]>.
On top of that, executeTool() doesn't take a tool-name string — it requires the actual tool object obtained from getTools().
Pass it a string, and you get a TypeError.
This was a spot where implementing based only on a summary of the docs would trip you up, plain and simple.

On `file://`, the handshake never finishes, for some reason

For postMessage between content.ts and injected.ts, I was using window.location.origin as targetOrigin.
On a page opened via file://, this becomes, for some reason, the literal string "null".
As a result, the handshake never completed at all, and the overlay would never show up.
I'm not sure whether this bug is fully reproducible, but thinking about it more, communication between the main world and isolated world within the same window shouldn't involve the concept of cross-origin at all in the first place.
So I changed targetOrigin to "*", and instead guarantee legitimacy via a random channel ID.
This was the type of bug you only notice by trying it with file://; if I hadn't verified the sample page by opening it directly via file://, I probably would have missed it.

The native implementation registers declarative forms on its own

When a native implementation is present, the browser itself may automatically register declarative forms.
In that case, this Extension's own registerTool() call fails as a "duplicate," but I'm treating that as expected behavior.
Since findAnnotatedFormByName() looks directly at the DOM to determine source: "declarative", it can report correctly regardless of who registered it.
There were also cases where the natively-synthesized inputSchema returned empty ({ type: "object", properties: {} }) on this particular build.
This is probably down to the state of the browser's implementation, not a bug in the Extension.

Tool execution results come back as strings, for some reason

The WebMCP spec's execute is originally meant to return "a string summary for the agent."
Because of that, I confirmed on real hardware that even when the page returns an object like { ok: true, city }, the browser's native implementation JSON-stringifies it before returning.
Neither the Extension nor the MCP Server touch result — they pass it straight through.
So the MCP client side needs to determine whether it got a string or structured data.

The Service Worker falls asleep on its own

An MV3 Service Worker gets suspended when it goes idle.
During that time, the WebSocket connection also drops.
It wakes back up automatically when a chrome.tabs event or similar fires, and the reconnection logic kicks in.
But if nothing happens right after startup — no tab activity at all — it can stay stuck at extensionConnected: false for a while.
If webmcp_get_status / webmcp_ping return false, doing something with the target tab (switching to it, reloading it, etc.) will bring it back.

Tool registration finishes before the handshake, so the overlay never shows up

On declarative-only pages (with no imperative JS at all), there was a race condition where tool registration could complete before the handshake with content.ts finished, leaving the overlay permanently hidden.
injected.ts registers <form toolname tooldescription> elements as soon as it finds them via MutationObserver.
So this race is more likely to occur on lightweight declarative-only pages that don't run any imperative script.
The previous implementation recorded "the manifest was sent / attempted to be sent" before the handshake had actually completed.
As a result, once the handshake did complete, a resend request would be misjudged as "no diff" and silently swallowed.
I fixed reportManifestIfChanged() so that it doesn't record or send anything at all until the channel is established.
I wrote a test that deliberately reproduces the bad ordering (tool registration → delayed handshake), and confirmed it reproduces the bug before the fix and resolves it after.
More than the bug itself, what I felt made the biggest difference was the approach of "write a test that deliberately reproduces the bad ordering, and use it to prove the fix works."

A tool that never comes back until a human clicks

Per the spec, a form without toolautosubmit stops by just focusing the submit button.
This is meant so a human reviews the content and submits manually.
At least some native implementations keep executeTool() itself blocked during this "waiting for a human" period.
This is not the same behavior as this Extension's polyfill, which immediately returns { pending: true, ... }.
If you call webmcp_call_tool on a tool without toolautosubmit in an automated environment with no human interaction, you won't get a response back until it times out.
Before calling it, you need to check whether webmcp_discover_tools's result has requiresUserGesture: true.

Testing: two tiers, with and without a browser

I verified the following four scenarios:

An imperative-only page (no <form>)
A declarative-only page (no registerTool() calls)
A page with a normal mix of imperative and declarative
A pattern where executing one tool changes whether another tool exists (calling unlock makes a new tool dynamically appear, and lock makes it disappear)

I actually loaded the Extension on Chrome for Testing and confirmed all patterns passed.
The fourth one also serves as verification of dynamic detection via the toolchange event and MutationObserver.
Since webmcp_discover_tools returns a cached result by default, you need forceRefresh: true to observe these dynamic changes.

I'm using Chrome for Testing (the Chromium bundled with Playwright) because, from Chrome 137 onward, official Google Chrome builds have removed the --load-extension flag for automation purposes.
Loading an extension manually via chrome://extensions works fine with regular Chrome.
But if you want to load an extension in automated tests, you need Chrome for Testing or Chromium.

On the MCP Server side, I use a mock class called FakeExtension.
It speaks the same WebSocket protocol as the real Extension, and lets me verify — without launching a browser — the connection state, the discover_tools cache/forceRefresh behavior, concurrent tool call execution, and cleanup on disconnect.
Since it doesn't launch a browser, it runs fast, so I split the work: bridge logic gets tested here, and verification that involves actual DOM manipulation goes through the Extension's Playwright tests.

A note on security (this is a prototype)

For postMessage between the main world (injected.ts) and the isolated world (content.ts), a random channel ID is issued once per page load, shared through a one-time handshake, and attached to every subsequent message. This is to prevent unrelated page scripts from injecting a fake manifest or fake execution results.
The MCP Server's WebSocket server binds only to 127.0.0.1, so it can't be connected to from anywhere other than the same machine.

This is built with personal use and prototyping in mind, and doesn't include additional authorization such as token authentication.
I stopped at the line of "good enough to run at the hands-on session" and haven't designed authorization with production use in mind.

Even so, there are real benefits

Even though I put this together somewhat forcefully, there are benefits I genuinely felt after actually using it.

Less guessing: the Agent doesn't have to infer the meaning of buttons or input fields on screen. The site itself can declare its intent as a tool.
Shorter execution: no need to replay a bunch of clicks and inputs — it can be handled directly as a tool call.
Visually verifiable: since it runs in the browser, a human can watch the result happen in real time.

But personally, I don't think it's necessary

From here on, this is entirely my personal opinion.
Honestly, having implemented it and used it at the hands-on session, what I felt most strongly was, "do we really need this?"

There are a few reasons.

First, the motivation to use a browser-embedded Agent is still weak.
Actually, I myself didn't even know Chrome had a built-in Agent until I did this investigation.
I imagine there are quite a few people in the same boat.

And WebMCP has the constraint that it only works while the page is open.
That's subtly restrictive.
Having a tool disappear the moment you switch tabs felt a bit inconvenient, coming from the mindset I'm used to with MCP.

In actual use, I didn't feel a particularly large difference in perceived token usage or execution speed between Agent-driven browser operations and WebMCP-driven ones.
For people who keep an existing Agent like Claude Code or Codex open at all times, I felt the appeal of going out of your way to open a browser-embedded Agent just to use this is pretty thin.

And honestly, from a layperson's perspective, I also wondered if the target audience selection itself might be a bit off.
The benefit itself — "fewer mistaken operations from the Agent" — is appealing.
But it's a bit of a shame that the place where you can realize that benefit is limited to something as little-known as a "browser-embedded Agent."

That said, it will resonate with the right people

That said, for people who use a browser-embedded Agent as part of their daily routine, the two points — "less guessing" and "shorter execution time" — should genuinely land hard.
I think the reason it didn't land as hard for me this time is simply that my own workflow wasn't built around a browser-embedded Agent to begin with.

Why I published this article anyway

Given how harsh some of this has been, you might wonder why I'm publishing it at all.
The reason is simple.
It felt like a waste to build an Extension and an MCP Server and have them only get used on the day of the hands-on session and nothing more.
Even though I have some skepticism about WebMCP as a spec, the technical insights I only gained by actually implementing it and getting my hands dirty — the async API, the origin issue, how I fixed the race condition, and so on — should be useful to someone on their own merits.
Also, if people end up using the extension or the MCP server, that makes me happy.

Summary

WebMCP is, directionally, an interesting spec: "the web page itself declares tools for an Agent."
That said, as of August 2026 it's still at the draft stage, and its target is limited to browser-embedded Agents.
So my personal conclusion is that, at this point, it doesn't land all that strongly for people who are already heavy users of existing MCP-capable Agents.
On the other hand, the pitfalls I found while implementing it — the async API, the origin issue, the race condition — should be useful reference material as native implementations spread further going forward.

Here's what I built and the related links:

Codelab: https://learn.gdgs.jp/webmcp-agent/
WebMCP Bridge MCP: https://github.com/tanahiro2010/webmcp-bridge-mcp
WebMCP Bridge Extension: https://github.com/tanahiro2010/webmcp-bridge-extension
connpass: https://gdgkwansai.connpass.com/event/391029
Original Article: https://qiita.com/tanahiro2010/items/66b7822e2132ec4e0a45

Feel free to check out the repos and reach out with any questions.

DEV Community: Hirohisa Tanaka

I Want to Be Graceful

I Want to Be Graceful

The takeaway

1. I wanted to be graceful

2. You can’t measure grace on the happy path

3. What is Graceful Degradation?

4. Don’t leave exceptions as exceptions

5. Let’s write ElegantPerson.ts

6. You can share grace with others

7. Conclusion

References

Cloudflare Agents Now Supports Pi 1.4: Testing Agent Interruption, Recovery, and Persistence

Article takeaway

1. Breaking down the four items in “Pi 1.4 support”

2. The roles of Pi, PiHarness, and Lifecycle

3. Persist the observations first

4. Conversation history and tasks survive a restart

5. The Agent keeps running after the client disconnects

6. Parked Tasks stop crash loops

7. Storage Error Recovery takes effect on the “next operation”

8. replay: "safe" does not protect side effects

9. Model Stream Retry checks error messages

10. Hibernation resumes on a different instance while waiting

11. Reproducing the agents@0.30.0 bug

12. Once you upgrade to Pi 1.4, you can’t go back to 1.3

13. What I learned by rerunning the tests

WebSocket event loss

Defining progress

A 19-minute model stream

14. Conclusion

References

MCP Step-Up Authorization vs. OAuth Incremental Authorization: What Actually Changes?

MCP Step-Up Authorization vs. OAuth Incremental Authorization: What Actually Changes?

TL;DR

1. The third step in a three-part rollout

2. Two versus 384

3. Step-up builds on RFC 6750

4. It was not a new feature in the 2026-07-28 spec

5. I wrote a client without the SDK

Two requested scopes, three granted

6. The challenge scope included the baseline

7. Who remembers? I got this wrong once

8. The server remembered them too—the approach the spec dropped

9. “There are no zones”

10. Refresh cannot add scopes

I wrote a conclusion without having measured it

11. The 2026-07-28 protocol has no initialize

12. So what actually changes?

13. Update: I reported it, and it was fixed that day (2026-10-21)

What changed

A useful implementation detail

Where this article stands

References

I Migrated a Cloudflare Agents Workspace and Measured Everything: What Changes When the Storage Format Changes?

TL;DR

1. The announcement

2. The old Workspace stored one file per row

3. The new Workspace separates inodes and chunks

4. Consequence #1: switching does not make old files visible

Add two controls

5. Consequence #2: the size limit changes when everything fits in one row

Measurement: where is the actual limit?

Why does the old implementation stop at 6 MiB?

6. Consequence #3: base64 conversion on every operation is slower

7. Consequence #4: content addressing enables deduplication

8. Consequence #5: there is nowhere to put some metadata

9. Consequence #6: you can move forward, but not backward

10. Running the migration guide's script

Symlinks need one extra check

11. Persistence survives hibernation

How long until hibernation?

12. Before you migrate

13. Conclusion

References

Investigating the Return of the PHP2Shell Nightmare

What this article concludes

1. What happened

2. What the official notice did—and did not—confirm

3. What Session Upload Progress does

8. `replay: "safe"` does not protect side effects

11. Reproducing the `agents@0.30.0` bug

6. The challenge `scope` included the baseline

11. The 2026-07-28 protocol has no `initialize`

7. The default-setting race, `enabled=0`, strict mode, and mod_php

`c.req.json()` Changes from `any` to `unknown`

Destructuring `c.req.query()` Starts Producing Errors Everywhere

Throwing Values That Aren't `Error` Instances

It's ESM-Only, but `require()` Still Works

10. `defineHandler()`: The “Fewer Choices” Philosophy in Action

First, Run `tsc --strict` (Type-Detectable Changes)

`jti` isn't random during the authorization-code exchange

`extractable: false` doesn't translate cleanly to Node.js