@mcp-b/do-runtime 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.7.0
+
+### Minor Changes
+
+- 3caa712: Move the reusable Chrome-host mechanics out of Rook: add a crash-safe browser alarm coordinator with durable transport recovery, package the MessagePort-backed WebSocket transport used between browser supervisors and actor workers, and share offscreen-document creation and stale-slot recovery.
+
+### Patch Changes
+
+- a2570d4: Ship a migration guide that separates Cloudflare Durable Object class lifecycle,
+  Drizzle application schemas, persisted Agents state, and runtime-owned storage.
+- 41b6ccc: Keep transformed foreign awaits visible to lifecycle checks until their continuations are published, and preserve native synchronous-iterable behavior in transformed `for await` loops.
+
+  Restore WebSocket auto-response configuration and timestamps when a host recreates an actor from its hibernation mirror.
+
+  Roll back failed SQLite WASM snapshot replacements and direct storage copies. If rollback also fails, retain the original database images in `SqliteWasmRestoreError.recoverySnapshot` for host recovery. This rollback is in memory; hosts needing replacement to survive process loss should restore into a fresh prefix before switching placement.
+
+  Correct the minimal-host setup and verify its documented TypeScript configuration and code against the files included in the package.
+
+## 0.6.1
+
+### Patch Changes
+
+- 55bae81: Export the shared in-memory hibernation mirror and browser WebSocket-upgrade adapter so embedders can reuse the reference host behavior instead of copying example shims.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -1,109 +1,243 @@
 # do-runtime
 
-Cloudflare's Durable Object runtime, ported from [workerd](https://github.com/cloudflare/workerd) to TypeScript, so the same actors run in a browser tab and in Node.
+![A local Agent running in an open browser-extension popup](docs/assets/extension-agent-runtime.svg)
+
+Cloudflare Durable Objects and Agents SDK code, running locally inside Chrome
+extensions and browser tabs.
+
+```ts
+import { Agent, callable } from "agents";
+
+export class Counter extends Agent<Cloudflare.Env, { count: number }> {
+  initialState = { count: 0 };
+
+  @callable()
+  increment() {
+    this.setState({ count: this.state.count + 1 });
+  }
+
+  @callable()
+  async armWake() {
+    await this.schedule(5, "scheduledIncrement");
+  }
+
+  scheduledIncrement() {
+    this.setState({ count: this.state.count + 1 });
+  }
+}
+```
+
+The [Chrome MV3 example](examples/extension/README.md) runs this ordinary Agent
+inside a module Worker. `setState()` persists to SQLite on OPFS; SDK calls and
+state sync cross a `MessagePort`-backed WebSocket; `schedule()` stores the task
+and projects its wake through `chrome.alarms`. Its end-to-end test destroys the
+offscreen host before the alarm fires, then proves Chrome rebuilds the runtime
+and calls `scheduledIncrement()` against the same state. Cloudflare runs the
+same Agent source inside workerd.
 
 [![CI](https://img.shields.io/github/actions/workflow/status/WebMCP-org/do-runtime/ci.yml?branch=main)](https://github.com/WebMCP-org/do-runtime/actions)
 [![License: FSL 1.1 MIT](https://img.shields.io/badge/license-FSL--1.1--MIT-orange.svg)](LICENSE)
 
-A Durable Object is an actor: one identity, one private SQLite database, one event at a time, reachable by name. That model only ran inside Cloudflare's edge. `do-runtime` is the runtime underneath it — input and output gates, implicit transactions, facets, alarms, Worker Loader, the `cloudflare:workers` module — rebuilt over two storage substrates: **sqlite-wasm on OPFS** inside a Web Worker, and **`node:sqlite`** in a Node process. Its behaviour is pinned by one conformance suite that runs against real workerd, against Node, and against headless Chromium, so "the same semantics" is something the tests assert rather than something this README claims.
+## The problem
+
+An `Agent` or `DurableObject` class is TypeScript, but its safety comes from the
+host around it. [Workerd](https://github.com/cloudflare/workerd) gives every named
+object a private SQLite database, gates storage access and event continuations,
+holds replies until their writes commit, delivers alarms, routes object-to-object
+calls, and restores hibernatable WebSockets. Cloudflare's Agents SDK relies on
+those rules.
+
+A browser has the raw components needed to build that host: dedicated workers,
+WebAssembly, OPFS, and `MessagePort`. It does not assemble them into a Durable
+Object runtime. A storage adapter alone would leave concurrency, commit ordering,
+wake-up, and lifecycle behavior undefined. Those differences surface when two
+requests overlap, Chrome evicts an extension context, or a reply races the write
+it reports.
+
+`do-runtime` supplies that missing host. It ports the relevant Durable Object
+behavior from workerd to TypeScript, runs each root actor in a Web Worker, stores
+its SQLite database in OPFS, and carries capabilities between workers with
+[Cap'n Web](https://github.com/cloudflare/capnweb). Supported `Agent` and
+`DurableObject` classes can execute on-device and deploy to Cloudflare from the
+same source. A `node:sqlite` backend provides a second local host and a fast test
+lane.
+
+The repository contains the runtime and the proofs needed to use it as an
+execution target:
+
+| Area | What it contains |
+| --- | --- |
+| [`@mcp-b/do-runtime`](src/) | Input and output gates, implicit transactions, Durable Object storage APIs, facets, alarms, hibernatable WebSockets, Worker Loader, and `cloudflare:workers`. |
+| [`vendor/agents/`](vendor/agents/README.md) | Rook's Agents SDK fork. It consumes the runtime; the runtime package does not import the SDK. |
+| [`conformance/`](conformance/) | One behavioral suite run against real workerd, the Node host, and the browser host in Chromium. |
+| [`examples/extension/`](examples/extension/README.md) | A Chrome MV3 host with an offscreen supervisor, local Agents SDK actors and sub-agents, OPFS persistence, durable alarms, hibernatable sockets, and restart recovery. |
+| [`examples/vibe-platform/`](examples/vibe-platform/README.md) | An in-tab editor that runs a user-authored Agent locally and exports the unchanged source as a Wrangler project. |
 
-It was extracted from Rook, SigVelo's AI agent for Chrome, which needed real Durable Object semantics under Cloudflare's Agents SDK inside a Chrome extension. Cloudflare, Workers, Durable Objects, and workerd are Cloudflare's; this is an independent port and is not affiliated with or endorsed by Cloudflare.
+This work was extracted from Rook, SigVelo's AI agent for Chrome. Cloudflare,
+Workers, Durable Objects, and workerd are Cloudflare's; this is an independent
+port and is not affiliated with or endorsed by Cloudflare.
 
 ## Contents
 
-- [The model: actors, and what a Durable Object adds](#the-model-actors-and-what-a-durable-object-adds)
-- [How it runs in the browser](#how-it-runs-in-the-browser)
-- [Quickstart](#quickstart)
+- [The browser runtime](#the-browser-runtime)
+- [Run it in a browser](#run-it-in-a-browser)
+- [Durable Object semantics](#durable-object-semantics)
+- [Minimal host](#minimal-host)
 - [Hosting an actor](#hosting-an-actor)
 - [Storage, alarms, facets, I/O](#storage)
+- [Migrations](#migrations)
 - [What is not supported, and stability](#what-is-not-supported)
 - [Package layout](#package-layout)
 - [Tests](#tests)
 - [Development](#development)
 - [Acknowledgements and license](#acknowledgements)
 
-## The model: actors, and what a Durable Object adds
+## The browser runtime
 
-An **actor** is the oldest answer to concurrency that does not involve locks: a unit of identity plus private state that processes one message at a time and talks to other actors only by sending messages. Nothing outside an actor can touch its state, so there is nothing to race. Erlang processes, Akka actors, Orleans grains, and Durable Objects are all this shape.
-
-A **Durable Object** is an actor with four things bolted on, and this package ports all four:
-
-| | What it means | Where it lives here |
-| --- | --- | --- |
-| **Named identity** | `idFromName("alice")` always means the same actor, and the id names its storage. | `ActorContainerOptions.id` + `uniqueKey`, `src/server/actor-id-impl.ts` |
-| **Private transactional storage** | A SQLite database only this actor can open. KV and SQL on the same file; writes coalesce into an implicit transaction that commits at the end of the event. | `src/io/actor-sqlite.ts`, `src/api/sql.ts`, `src/util/` |
-| **Input and output gates** | The single-threaded illusion survives `await`. The input gate admits one event at a time (and re-admits a continuation only through a gated primitive); the output gate holds a reply until the write it could reveal is durable. | `src/io/io-gate.ts`, `src/io/io-context.ts` |
-| **Alarms and facets** | `setAlarm()` wakes the actor later with retries and backoff. Facets are child actors under a root: own gates, own database, one tree index. | `src/server/alarm-scheduler.ts`, `src/server/facet-*.ts` |
-
-Two consequences fall out of the gates and are the whole reason the runtime is more than a SQLite wrapper:
-
-- **No interleaving.** If a method awaits storage, a second call on the same actor waits. Application code reads and writes state without locks and is still correct.
-- **No phantom reads.** A reply that could expose a write does not leave until that write is committed. A crash between "returned" and "committed" cannot lie to a caller.
-
-Everything else in the package serves those two lines.
-
-## How it runs in the browser
-
-Workerd gives every actor its own isolate, so `setTimeout`, `fetch`, and `scheduler.wait` can only ever mean the one actor in that isolate. The browser equivalent is **one root actor per Web Worker**, with the page acting as the supervisor workerd's `Server` is:
+Workerd tracks each actor's I/O context inside a Worker isolate;
+[multiple actors can share that isolate](https://developers.cloudflare.com/durable-objects/reference/in-memory-state/).
+The reference browser host places one root actor in each Web Worker so its
+ambient timers, `fetch`, and `scheduler` resolve to that root.
+The page, or an extension's offscreen document, supervises placement and owns no
+actor storage.
 
 ```mermaid
 flowchart TB
-  subgraph page["Page — the supervisor (owns no storage)"]
-    S["spawns workers · actor registry · routes actor→actor calls · owns alarm delivery"]
+  subgraph page["Page or offscreen document / supervisor"]
+    S["spawns workers; actor registry; routes actor calls; owns alarm delivery"]
   end
 
-  subgraph wa["Web Worker — actor alice"]
+  subgraph wa["Web Worker / actor alice"]
     direction TB
-    Ca["ActorContainer<br/>input gate · output gate · state · globals"]
-    Fa["facet containers<br/>(own gates + db, same realm)"]
-    Pa[("one OPFS SAH pool<br/>sqlite-wasm")]
+    Ca["Agent or DurableObject<br/>inside ActorContainer<br/>input gate; output gate; globals"]
+    Fa["facet containers<br/>(own gates and database, same realm)"]
+    Pa[("sqlite-wasm<br/>OPFS SAH pool")]
     Ca --- Fa
     Ca --> Pa
     Fa --> Pa
   end
 
-  subgraph wb["Web Worker — actor bob"]
+  subgraph wb["Web Worker / actor bob"]
     direction TB
-    Cb["ActorContainer"]
-    Pb[("OPFS SAH pool")]
+    Cb["Agent or DurableObject<br/>inside ActorContainer"]
+    Pb[("sqlite-wasm<br/>OPFS SAH pool")]
     Cb --> Pb
   end
 
-  subgraph wal["Web Worker — alarms"]
+  subgraph wal["Web Worker / alarms"]
     direction TB
-    A["AlarmScheduler<br/>_cf_ALARM · retry ladder · backoff"]
-    PA[("OPFS SAH pool")]
+    A["AlarmScheduler<br/>_cf_ALARM; retries; backoff"]
+    PA[("sqlite-wasm<br/>OPFS SAH pool")]
     A --> PA
   end
 
-  S <-- "MessagePort · Cap'n Web" --> Ca
-  S <-- "MessagePort · Cap'n Web" --> Cb
-  S <-- "MessagePort · Cap'n Web" --> A
+  S <-- "MessagePort + Cap'n Web" --> Ca
+  S <-- "MessagePort + Cap'n Web" --> Cb
+  S <-- "MessagePort + Cap'n Web" --> A
 ```
 
 Why it is shaped this way:
 
-- **The page cannot hold storage.** OPFS synchronous access handles — the only way to run SQLite synchronously in a browser — exist only inside a dedicated worker. So the page is a pure supervisor: it creates workers, keeps the registry, and routes `alice → bob` calls. It is the offscreen document's job in a Chrome extension and `Server`'s job in workerd.
-- **One root actor per worker.** The worker entry calls `installActorScope(globalThis, () => container.globals)`, which installs gated `setTimeout`, `clearTimeout`, `setInterval`, `clearInterval`, `fetch`, `crypto`, and `scheduler` as the worker's ambient globals. With one root per realm the ambient is unambiguous, which is exactly why workerd gets this for free and why application code — and any SDK it pulls in — needs no changes.
-- **Facets stay in their parent's worker**, as they stay in their parent's isolate upstream. A facet is a separate `ActorContainer` with its own gates and its own database prefix inside the parent's pool; what it shares is the JavaScript realm and the root's synchronous facet-tree index, which is what lets a facet have facets of its own.
-- **Alarms get their own worker** because the scheduler needs a database and a database needs a worker. Setting an alarm is one durable row there; delivery comes back through the supervisor, which places the target actor if it is not running.
-- **Every hop is `MessagePort` + [Cap'n Web](https://github.com/cloudflare/capnweb).** Each worker is booted with one raw `postMessage` carrying its port; everything after is a capability-based RPC session opened by `newRpcSession()`. A container's `entry(instance)` proxy is what sits behind the session, so every call from outside is one gated event.
+- OPFS synchronous access handles exist only inside a dedicated worker, so the
+  supervisor creates workers, keeps the registry, and routes calls between them.
+- Each root gets its own worker. `installActorScope()` can therefore install the
+  actor's gated timers, `fetch`, `crypto`, and `scheduler` as unambiguous ambient
+  globals for application and SDK code.
+- Facets stay in their parent's worker, matching workerd's isolate layout. Each
+  facet still has its own container, gates, and database prefix.
+- The reference host gives its alarm scheduler a separate worker because the
+  scheduler has durable SQLite state of its own. A single-root host can colocate
+  it with the actor worker, as the MV3 example does. Either layout can place a
+  sleeping actor when a stored alarm becomes due.
+- Each cross-worker call is a capability-based RPC session over a transferred
+  `MessagePort`. The proxy exposed by `container.entry(instance)` turns each call
+  into one gated actor event.
 
-Boot order inside an actor worker is load-bearing; each inversion below is a measured failure, not a style choice:
+`conformance/browser/` is that picture, runnable: [`host.ts`](conformance/browser/host.ts) is the page, [`actor.worker.ts`](conformance/browser/actor.worker.ts) is a worker hosting one actor tree over OPFS, [`alarms.worker.ts`](conformance/browser/alarms.worker.ts) is the scheduler, and [`protocol.ts`](conformance/browser/protocol.ts) is the three RPC surfaces between them.
 
-1. Capture raw platform timers at module scope and build the `Timer` port on them — a `Timer` that reads the installed globals recurses once the scope is in.
-2. Set `globalThis.sqlite3ApiConfig = { disable: { vfs: { opfs: true, "opfs-wl": true } } }` before touching sqlite — only the SAH pool is wanted, and the other two VFSes spawn workers and arm watchdogs of their own.
-3. `sqlite3InitModule()` and `installOpfsSAHPoolVfs(...)` **before** `installActorScope` — the installer arms watchdogs through the global `setTimeout`, which must not yet be the actor's gate.
-4. `installActorScope(globalThis, resolve)` with a `resolve` that throws when the container is gone, so a torn-down worker refuses instead of falling through to raw timers.
-5. Application pool settings, not the conformance lane's test-only ones: a stable pool name (it becomes an OPFS directory name), `clearOnInit: false`, capacity sized to two databases per root plus journals. The pool takes exclusive sync access handles — one holder per pool; a second context fails to install.
+## Run it in a browser
 
-`conformance/browser/` is that picture, runnable: [`host.ts`](conformance/browser/host.ts) is the page, [`actor.worker.ts`](conformance/browser/actor.worker.ts) is a worker hosting one actor tree over OPFS, [`alarms.worker.ts`](conformance/browser/alarms.worker.ts) is the scheduler, and [`protocol.ts`](conformance/browser/protocol.ts) is the three RPC surfaces between them.
+The Chrome MV3 extension is the primary reference host. From a fresh checkout:
+
+```bash
+pnpm sdk:setup
+pnpm install
+pnpm exec playwright install chromium
+pnpm --filter do-runtime-example-extension e2e
+```
+
+| Example | Browser shape | What the test proves |
+| --- | --- | --- |
+| [Chrome MV3 extension](examples/extension/README.md) | Service worker -> offscreen document -> actor Worker -> sqlite-wasm/OPFS | An Agents SDK root and its sub-agents retain state across host teardown; alarms wake an evicted host; hibernatable sockets, state sync, callable RPC, queues, MCP, and email routing use the real SDK paths. |
+| [In-tab coding platform](examples/vibe-platform/README.md) | Page -> workspace Worker and authored-Agent Worker -> sqlite-wasm/OPFS | A user-authored Agent runs against durable local state, survives code replacement, and exports from the browser as the same source in a Wrangler project. |
+
+Run both browser end-to-end suites with `pnpm test:examples`.
+
+The [in-tab coding platform](examples/vibe-platform/README.md) is the second
+composition: an editor, local preview, persisted Agent state, and Wrangler
+export, all inside a normal browser tab.
+
+![The vibe-platform example running an Agents SDK Agent in a browser, with the Agent source on the left and its SQLite-backed application on the right](docs/assets/browser-agent-runtime.png)
+
+Start it at `http://localhost:5173` with
+`pnpm --filter do-runtime-example-vibe-platform dev`.
+
+## Durable Object semantics
+
+An actor has an identity and private state. A Durable Object adds gates that
+serialize event slices and storage access, plus storage and lifecycle behavior
+that survives process loss:
+
+| | What it means | Where it lives here |
+| --- | --- | --- |
+| **Named identity** | `idFromName("alice")` always means the same actor, and the id names its storage. | `ActorContainerOptions.id` + `uniqueKey`, `src/server/actor-id-impl.ts` |
+| **Private transactional storage** | A SQLite database only this actor can open. KV and SQL share the file; writes coalesce into implicit transactions that commit at gate-release boundaries. | `src/io/actor-sqlite.ts`, `src/api/sql.ts`, `src/util/` |
+| **Input and output gates** | The input gate serializes event slices across `await`. The output gate holds a reply until the write it could reveal is durable. | `src/io/io-gate.ts`, `src/io/io-context.ts` |
+| **Alarms and facets** | `setAlarm()` wakes the actor later with retries and backoff. Facets are child actors with their own gates and database under a root. | `src/server/alarm-scheduler.ts`, `src/server/facet-*.ts` |
+
+With the default storage options, a method awaiting storage holds other calls
+back, so a read-modify-write that only awaits storage needs no extra lock.
+Awaiting external I/O such as `fetch()` releases the input gate: another event
+can run before the method resumes. Use
+[`blockConcurrencyWhile()`](https://developers.cloudflare.com/durable-objects/api/state/#blockconcurrencywhile)
+when an async operation must exclude other events. A reply that exposes a write
+waits for that write to commit, so a crash cannot leave a caller holding an
+acknowledgement for data that never became durable.
 
-## Quickstart
+## Minimal host
 
-Install with `pnpm add @mcp-b/do-runtime`. The package ships ESM JavaScript and declarations and requires Node ≥ 24.11 when using the `node:sqlite` backend.
+Install with `pnpm add @mcp-b/do-runtime`. The package ships ESM JavaScript and
+declarations. The shortest complete host uses the `node:sqlite` backend, which
+requires Node 24.11 or newer. Browser hosts place the same container inside a
+Web Worker and supply the sqlite-wasm backend shown in the runnable examples.
+
+For a standalone TypeScript host, install the ambient Node and Workers types:
+
+```bash
+pnpm add -D typescript @types/node @cloudflare/workers-types@5.20260820.1
+```
+
+Use the following `tsconfig.json`. An existing Workers project can keep its
+generated Cloudflare types instead of loading `@cloudflare/workers-types` too.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "NodeNext",
+    "lib": ["ESNext"],
+    "types": ["node", "@cloudflare/workers-types"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  }
+}
+```
+
+Save this as `host.mts` and run `pnpm exec tsc && node host.mts`:
 
 ```ts
+import { mkdir } from "node:fs/promises";
 import { DurableObject } from "@mcp-b/do-runtime/cloudflare-workers";
 import { createActorContainer, DEFAULT_ALARM_OUTLET, noFacets, type Timer } from "@mcp-b/do-runtime";
 import { createNodeSqlProvider } from "@mcp-b/do-runtime/backends/node-sqlite";
@@ -133,6 +267,7 @@ const timer: Timer = {
     }),
 };
 
+await mkdir("./data", { recursive: true });
 const container = await createActorContainer({
   id: "counter-1",
   uniqueKey: "my-app", // keep this stable forever: every DurableObjectId is derived from it
@@ -151,14 +286,12 @@ await counter.increment(); // 1
 await counter.increment(); // 2
 ```
 
-Open a second container over the same directory and `increment()` answers `3`: the instance was volatile, the storage was not. In a browser the only line that changes is `sql`, which becomes `createSqliteWasmProvider(pool, { prefix: "/counter-1" })` from `@mcp-b/do-runtime/backends/sqlite-wasm`.
-
-## Examples
-
-Two runnable browser hosts live in [`examples/`](examples/), each with its own README and Playwright e2e (`pnpm test:examples`):
-
-- [`examples/extension/`](examples/extension/) — a Chrome MV3 compatibility harness: service worker → offscreen document (with corpse recovery) → worker hosting an Agents SDK `Counter` and local sub-agents. Proves persistent state, sibling and nested facet isolation, overlapping async work, abort/delete lifecycle, sub-agent scheduling across host recreation, exclusive host ownership, hibernating `AgentClient` WebSockets, state sync, callable and streaming RPC, SDK queues, stateless MCP, inbound email routing, the MV3 CSP story (`'wasm-unsafe-eval'`), and `chrome.alarms` recreation of an evicted host before durable alarm delivery.
-- [`examples/vibe-platform/`](examples/vibe-platform/) — a self-contained vibe-coding page that authors both a front-end and an Agents SDK `Agent`, runs them in-tab with durable SQLite-backed state, and exports the unchanged sources as a Wrangler project that passes `wrangler deploy --dry-run`.
+Open a second container over the same directory and `increment()` answers `3`:
+the instance was volatile, the storage was not. Inside an initialized actor
+worker, the browser host supplies
+`createSqliteWasmProvider({ pool, capi: sqlite3.capi }, { prefix: "/counter-1" })` from
+`@mcp-b/do-runtime/backends/sqlite-wasm`. The supervisor, OPFS pool, and worker
+bootstrapping are shown in the browser examples above.
 
 ## Hosting an actor
 
@@ -190,6 +323,27 @@ The lifecycle:
 6. Watch `container.onBroken`; dispose the placement; recreate it on the next event over the same storage. A failed `blockConcurrencyWhile()` rejects its caller with `BrokenActorError` and breaks the placement with that same error.
 7. Before evicting, inspect `container.quiescence()`. Mirror live sockets through `ports.hibernation`, then build the replacement with `webSockets`; do not reconnect or call `acceptWebSocket()` again.
 
+### Browser worker boot order
+
+The order inside an actor worker is load-bearing. Each inversion below has a
+measured failure in the browser test lane:
+
+1. Capture raw platform timers at module scope and build the `Timer` port on
+   them. Reading the installed globals from that port recurses after the actor
+   scope replaces them.
+2. Set
+   `globalThis.sqlite3ApiConfig = { disable: { vfs: { opfs: true, "opfs-wl": true } } }`
+   before initializing sqlite. The host uses the SAH pool; the other OPFS VFSes
+   spawn workers and arm watchdogs of their own.
+3. Run `sqlite3InitModule()` and `installOpfsSAHPoolVfs(...)` before
+   `installActorScope`. The pool installer uses global timers during startup.
+4. Install the actor scope with a resolver that throws when its container is
+   gone. A torn-down worker must refuse new work instead of falling through to
+   ungated platform timers.
+5. Use a stable pool name, preserve files with `clearOnInit: false`, and size the
+   pool for two databases per root plus journals. The pool owns exclusive sync
+   access handles, so another context cannot open it at the same time.
+
 For a standard Durable Object binding, call
 `createDurableObjectNamespace(uniqueKey, channel)` and put the result in `env`
 and `ctx.exports`. The channel maps each routed id to a placed `Fetcher`; that
@@ -207,15 +361,31 @@ re-enters the owning input gate.
 
 `SqlDatabaseProvider.open(name)` is the runtime execution seam. The runtime owns database names, tables, transactions, reset behaviour, facet metadata, and streaming `sql.ingest()` statement boundaries; the host chooses the physical provider and prefix. Stored KV values use structured-clone semantics across workerd, Node, and the browser; existing JSON rows remain readable. `_cf_` names are reserved to the runtime.
 
-Schema migrations work exactly as on Cloudflare, at both layers. An application migrates its own tables in its constructor — synchronous DDL under boot semantics, or `ctx.blockConcurrencyWhile()` when the path is async; the Agents SDK's versioned `_ensureSchema` and Drizzle's `durable-sqlite` migrator (`drizzle-kit generate` compiled into the bundle, `migrate()` in the constructor) run unchanged, the latter pinned end-to-end by [`src/drizzle-migrations.test.ts`](src/drizzle-migrations.test.ts). The runtime's own `_cf_` tables are versioned separately, per database file, in `PRAGMA user_version`: [`src/util/sqlite-migrations.ts`](src/util/sqlite-migrations.ts) brings an older file forward at open — before any event can enter — a file or imported snapshot stamped by a newer release refuses with the remedy named, and application SQL cannot reach the stamp, because `sql.exec()` enforces workerd's pragma allowlist (decision 19).
+### Migrations
+
+Wrangler class declarations, application SQL migrations, persisted `Agent.state`,
+Agents SDK tables, and runtime-owned tables have separate owners. Application
+SQL uses the same Drizzle migration bundle and constructor pattern on Cloudflare
+and on this runtime; `do-runtime` adds no application migration registry. See
+[`docs/migrations.md`](docs/migrations.md) for the Rook-facing workflow and the
+upstream Cloudflare and Drizzle references.
+
+The runtime's own `_cf_` tables are versioned per database file in
+`PRAGMA user_version`. [`src/util/sqlite-migrations.ts`](src/util/sqlite-migrations.ts)
+brings older files forward before any event enters and refuses storage written by
+a newer package version. Application SQL cannot access that runtime-owned stamp.
 
 The browser provider takes an already-installed OPFS SAH pool (`installOpfsSAHPoolVfs`; sync access handles in a dedicated worker — no cross-origin isolation or `SharedArrayBuffer` needed). One pool per worker; the root and each local facet get separate prefixes inside it. `SqliteWasmActorStorage` adds the close, physical delete, and clone operations a local placement host needs around one prefix. The Node provider uses in-memory databases by default and a directory when asked.
 
 Both concrete providers also implement `SqlDatabaseSnapshotProvider`. After the host has stopped the actor, `provider.close()` releases every database handle; `exportSnapshot()` then returns the SQLite images for the whole actor storage scope, and `importSnapshot()` replaces an idle scope. The same snapshot can seed a cold local replica because SQLite images are portable between these providers. Node snapshots require a dedicated directory-backed provider. This is backup/restore and replica seeding, not Cloudflare's time-indexed PITR or continuously updated read replication.
 
+The browser provider attempts to restore the original images when a snapshot import or direct `SqliteWasmActorStorage.copyFrom()` replacement fails; `SqliteWasmRestoreError.recoverySnapshot` retains those images if rollback also fails. This rollback lives in memory and cannot survive Worker or process loss during replacement; a host requiring that guarantee must import into a fresh prefix and durably switch placement after success.
+
 ### Alarms
 
-Construct one `AlarmScheduler` per namespace over a `SqlDatabase` of its own. It owns `_cf_ALARM`, delivery, retry counts (`ALARM_RETRY_MAX_TRIES`), exponential backoff with jitter, and abandonment. Pass `scheduler.hooks(id)` as a root actor's `ports.alarms`, and give the scheduler a `getActor(id)` that places the actor if it is not running — an alarm is a reason to wake a Durable Object, not something that needs one awake already. A browser host may project the scheduler's current one-shot wait onto a physical timer (`chrome.alarms`, say) but must not duplicate delivery policy.
+Construct one `AlarmScheduler` per namespace over a `SqlDatabase` of its own. It owns `_cf_ALARM`, delivery, retry counts (`ALARM_RETRY_MAX_TRIES`), exponential backoff with jitter, and abandonment. Pass `scheduler.hooks(id)` as a root actor's `ports.alarms`, and give the scheduler a `getActor(id)` that places the actor if it is not running — an alarm is a reason to wake a Durable Object, not something that needs one awake already.
+
+A suspending browser host can project the scheduler's next wake through `BrowserAlarmCoordinator` from `@mcp-b/do-runtime/browser/alarm-coordinator`. The coordinator journals the physical hop, rejects stale projections, rearms a consumed watchdog, and reconciles after background-worker restart. The host supplies durable journal storage, the physical alarm calls, and delivery back into its scheduler; logical delivery policy remains in `AlarmScheduler`.
 
 ### Facets
 
@@ -241,6 +411,16 @@ registry is populated before the constructor, so SDKs can lazily rebuild their
 connection wrappers without another upgrade or connect hook. Closed sockets are
 removed before `webSocketClose` runs.
 
+`HibernationMirror` is the package's in-memory reference implementation. Seed a
+replacement mirror with the prior socket snapshot and auto-response pair, then
+pass that mirror to `ports.hibernation` and its `snapshot()` to `webSockets`.
+Browser hosts can install the remaining Request/Response upgrade accommodation
+from `@mcp-b/do-runtime/browser`; the runtime itself supplies `WebSocketPair`.
+Hosts whose actor lives in another Worker can use `MessagePortWebSocket`,
+`createMessagePortWebSocketConstructor`, and `serveMessagePortWebSockets` from
+`@mcp-b/do-runtime/browser/message-port-websocket`; binary frames stay in
+structured clone and each socket gets one dedicated `MessagePort`.
+
 `container.quiescence()` reports armed timers, pending `waitUntil` work, input
 lock state, and output-gate breakage without waiting. `drainWaitUntil()` is for
 shutdown and intentionally never settles while a live interval remains armed.
@@ -280,10 +460,12 @@ This is `0.x`. The public surface is what [`src/index.ts`](src/index.ts) and the
 | `src/io/` | Gates, invocation context, actor storage engine, ids, Worker channels |
 | `src/api/` | Workers-facing APIs: `DurableObjectState`, SQL, WebSocket, Worker Loader, `cloudflare:workers` |
 | `src/server/` | Actor containers, facet lifecycle, deletion recovery, alarm scheduling |
+| `src/browser/` | Physical alarm projection, offscreen-document recovery, and MessagePort-backed WebSockets for browser hosts |
 | `src/transport/` | The one `MessagePort` Cap'n Web session adapter |
 | `backends/` | `node:sqlite` and sqlite-wasm/OPFS `SqlDatabaseProvider`s |
 | `conformance/` | One suite, three hosts: workerd, Node, browser; plus the probe fixture and benchmarks |
 | `examples/` | Runnable browser hosts: an MV3 extension and an in-page vibe-coding platform |
+| `docs/migrations.md` | How Rook evolves Wrangler declarations, application SQL, and persisted Agent state without duplicating Cloudflare's migration machinery |
 | `docs/decisions.md` | The numbered invariants and decisions that source comments cite (`§1.2`, `decision 8`) |
 
 The `util → io → api → server` direction follows workerd's own layering, enforced with TypeScript project references. Source comments cite the workerd file and line they port (`← io-gate.c++:142`), and every deliberate divergence is recorded beside its implementation and in a conformance row.
@@ -305,11 +487,19 @@ The workerd lane is what makes the others mean something: every row it passes is
 ```bash
 git clone https://github.com/WebMCP-org/do-runtime
 cd do-runtime
+pnpm sdk:setup
 pnpm install
 pnpm exec playwright install chromium   # browser lane only
 pnpm typecheck && pnpm test
+pnpm sdk:check && pnpm sdk:test          # Rook's Agents SDK fork
 ```
 
+The repository has two independently tested layers: the runtime at the root
+and Rook's six-package Agents SDK fork in
+[`vendor/agents/`](vendor/agents/README.md). The examples consume the fork's
+built `agents` package through a `file:` dependency, which resolves their
+own peer dependencies without installing a second SDK implementation.
+
 Change runtime behaviour with the corresponding workerd source open (line citations use release `v1.20260713.1`; the conformance oracle is pinned to `v1.20260820.1`). Ask the workerd lane an observable question before inventing a local rule; record any intentional divergence in the table above and in a conformance row. Keep host seams small and typed, keep gates internal, and keep product knowledge out of the port. See [`docs/decisions.md`](docs/decisions.md) for the invariants the code cites.
 
 ## Acknowledgements

package/dist/backends/sqlite-wasm.d.ts

@@ -23,7 +23,7 @@
  * drives this file directly, and by the conformance suite, which runs the whole
  * package over it.
  */
-import { type SqlDatabase, type SqlDatabaseProvider, type SqlDatabaseSnapshotProvider, type SqlDatabaseStatement, type SqlResult, type SqlValue } from "../src/util/sqlite.js";
+import { type SqlDatabase, type SqlDatabaseProvider, type SqlDatabaseSnapshot, type SqlDatabaseSnapshotProvider, type SqlDatabaseStatement, type SqlResult, type SqlValue } from "../src/util/sqlite.js";
 /** ← `PreparedStatement`, the members used here. */
 export interface SqliteWasmStatement {
     readonly columnCount: number;
@@ -113,6 +113,11 @@ export declare class SqliteWasmActorStorage implements SqlDatabaseProvider {
     copyFrom(source: SqliteWasmActorStorage): Promise<void>;
 }
 export declare function createSqliteWasmProvider(host: SqliteWasmHost, options: SqliteWasmProviderOptions): SqlDatabaseSnapshotProvider;
+/** A failed rollback retains the original images so the host can recover to another prefix. */
+export declare class SqliteWasmRestoreError extends AggregateError {
+    readonly recoverySnapshot: SqlDatabaseSnapshot;
+    constructor(errors: unknown[], recoverySnapshot: SqlDatabaseSnapshot);
+}
 export declare class SqliteWasmDatabase implements SqlDatabase {
     #private;
     private readonly onClose;

package/dist/backends/sqlite-wasm.js

@@ -81,8 +81,11 @@ var SqliteWasmActorStorage = class {
 				bytes: new Uint8Array(await source.#host.pool.exportFile(file))
 			});
 		}
-		this.deleteAll();
-		for (const { name, bytes } of images) await this.#host.pool.importDb(`${this.#prefix}.${name}.sqlite`, bytes);
+		this.close();
+		await replaceDatabases(this.#host.pool, this.#prefix, images.map(({ name, bytes }) => ({
+			name,
+			image: bytes
+		})));
 	}
 	#ownedFiles() {
 		return this.#host.pool.getFileNames().filter((name) => name.startsWith(`${this.#prefix}.`));
@@ -126,11 +129,73 @@ function createSqliteWasmProvider(host, options) {
 			requireClosed(openDatabases);
 			requireValidSqlDatabaseSnapshot(snapshot);
 			requireImportableRuntimeStorage(snapshot);
-			for (const file of ownedFiles()) host.pool.unlink(file);
-			for (const { name, image } of snapshot.databases) await host.pool.importDb(`${prefix}.${name}.sqlite`, new Uint8Array(image));
+			await replaceDatabases(host.pool, prefix, snapshot.databases);
 		}
 	};
 }
+/** A failed rollback retains the original images so the host can recover to another prefix. */
+var SqliteWasmRestoreError = class extends AggregateError {
+	recoverySnapshot;
+	constructor(errors, recoverySnapshot) {
+		super(errors, "SQLite replacement and rollback failed; restore recoverySnapshot to an idle provider.");
+		this.recoverySnapshot = recoverySnapshot;
+		this.name = "SqliteWasmRestoreError";
+	}
+};
+async function replaceDatabases(pool, prefix, databases) {
+	const replacement = databases.map(({ name, image }) => ({
+		name,
+		image: new Uint8Array(image)
+	}));
+	const ownedFiles = () => pool.getFileNames().filter((file) => file.startsWith(`${prefix}.`));
+	const files = ownedFiles();
+	requireNoRecoverySidecars(files);
+	const original = [];
+	for (const file of files) {
+		const name = file.slice(prefix.length + 1, -7);
+		requireSafeDatabaseName(name);
+		original.push({
+			name,
+			image: new Uint8Array(await pool.exportFile(file))
+		});
+	}
+	const touched = /* @__PURE__ */ new Set();
+	try {
+		for (const file of files) {
+			touched.add(file);
+			if (!pool.unlink(file)) throw new Error(`SAH pool did not unlink ${file}`);
+		}
+		for (const { name, image } of replacement) {
+			const file = `${prefix}.${name}.sqlite`;
+			touched.add(file);
+			await pool.importDb(file, image);
+		}
+	} catch (error) {
+		const errors = [error];
+		for (const file of ownedFiles()) {
+			if (!touched.has(file)) continue;
+			try {
+				if (!pool.unlink(file)) throw new Error(`SAH pool did not unlink ${file}`);
+			} catch (rollbackError) {
+				errors.push(rollbackError);
+			}
+		}
+		for (const { name, image } of original) {
+			const file = `${prefix}.${name}.sqlite`;
+			if (!touched.has(file)) continue;
+			try {
+				await pool.importDb(file, new Uint8Array(image));
+			} catch (rollbackError) {
+				errors.push(rollbackError);
+			}
+		}
+		if (errors.length > 1) throw new SqliteWasmRestoreError(errors, {
+			version: 1,
+			databases: original
+		});
+		throw error;
+	}
+}
 var SqliteWasmDatabase = class {
 	onClose;
 	#host;
@@ -255,6 +320,6 @@ function firstCompleteStatement(capi, sql) {
 	return sql;
 }
 //#endregion
-export { SqliteWasmActorStorage, SqliteWasmDatabase, createSqliteWasmProvider };
+export { SqliteWasmActorStorage, SqliteWasmDatabase, SqliteWasmRestoreError, createSqliteWasmProvider };
 
 //# sourceMappingURL=sqlite-wasm.js.map