@mcp-b/do-runtime 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- 0821d6e: Replace the fail-closed Durable Object WebSocket stubs with workerd-compatible hibernatable WebSockets.
+
+  `WebSocketPair`, `WebSocketRequestResponsePair`, all eight `DurableObjectState` WebSocket methods, tags, structured-clone attachments, auto-responses, event timeouts, close state, and `webSocketMessage`/`webSocketClose`/`webSocketError` dispatch now run through actor input and output gates. `installActorScope()` installs the three WebSocket globals alongside the existing actor-scoped primitives.
+
+  Embedders that evict live actors can mirror socket state through the new optional `ports.hibernation` callbacks and rehydrate it through `ActorContainerOptions.webSockets` before the next constructor runs. `container.quiescence()` exposes the non-blocking eviction signals, and `gateHooks` makes both gates observable.
+
+  This is a breaking replacement for the exported hibernation-unavailable error and the previous `never`-typed methods. Hosts should remove reconnect-only fallbacks; applications can use the Agents SDK and PartyServer hibernation defaults.
+
+## 0.5.0
+
+### Minor Changes
+
+- bef6bd8: `storage.put()` now reads its arguments the way JSG does, instead of silently dropping writes.
+
+  A non-string, non-object key previously fell into the multi-key overload, where `Object.entries` on a primitive is `[]` — so the call resolved having written nothing. It now stringifies the key as the `kj::String` alternative does: `put(123, v)` writes `"123"`, `put(null, v)` writes `"null"`, `put(undefined, v)` writes `"undefined"`, `put([["a", 1]], v)` writes `"a,1"`, and a symbol key throws V8's own conversion error.
+
+  Once the key does unwrap as a dictionary, a second argument that is a non-null primitive is now refused with upstream's own message rather than spread into the options — `put({a: 1}, "v")` wrote key `a` with `{0: "v"}` for options. The refusal models workerd's all-optional options struct exactly: `null`, arrays and functions all unwrap to default options and the write proceeds, as measured on real workerd. Functions take the dictionary alternative in the KEY position too, so `put(function f(){}, v)` is refused rather than writing a row keyed on the function's source text.
+
+  Measured on real workerd and pinned by a conformance row that runs on all three lanes.
+
+- bef6bd8: `sql.exec()` and `sql.ingest()` now refuse the SQL forms workerd's authorizer refuses but its regulator never sees. SQL that uses them throws where it previously ran.
+
+  `ATTACH`, `DETACH`, the temp-schema creations, and virtual-table modules outside upstream's four reach SQLite action codes rather than `SqlStorageRegulator` callbacks, so porting the regulator whole left them unguarded. Each refuses with workerd's own message, `not authorized: SQLITE_AUTH`, except `VACUUM`, which carries SQLite's `cannot VACUUM from within a transaction: SQLITE_ERROR` because upstream refuses it by the transaction a Durable Object always has open.
+
+  `ATTACH` was an isolation boundary and not only a fidelity gap: both backends open a real database file, so application SQL could attach another actor's database and read every application table in it — the reserved-name scan sees only the submitted statement — and `VACUUM INTO` could write any file the process can. The temp schema is refused by both of its spellings, `CREATE TEMP TABLE` and `CREATE TABLE temp.t`; the second was the live gap, where the table was created, written and read back. Of the virtual-table modules, `dbstat` is the one that mattered: it reports a row per table, so it enumerated the runtime's own `_cf_` tables and their sizes without the statement ever naming them. The table name and the module accept every quoting SQLite does — double quotes, backticks, brackets, and the misquoting feature's single-quoted string — with the module resolved before the allowlist, exactly as workerd's authorizer sees it; a `CREATE VIRTUAL TABLE` whose module cannot be read is refused outright.
+
+  A leading `;` now counts as trivia for every leading-keyword refusal in the file, including the pre-existing transaction-control and pragma checks. `node:sqlite` reports an empty first statement as part of the span it compiled, so `;ATTACH …` read as a statement whose keyword was `;` and passed all three.
+
+  `PRAGMA page_size` is now allowed with no argument, as upstream's allowlist has it for the R\*Tree module's own internal read; `PRAGMA page_size = N` is still refused. That was a false refusal — code that runs on Cloudflare failed here.
+
+  Every form, refused and allowed alike, was measured on real workerd and is pinned by a conformance row that runs on all three lanes.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -157,7 +157,7 @@ Open a second container over the same directory and `increment()` answers `3`: t
 
 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, non-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/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`.
 
 ## Hosting an actor
@@ -175,6 +175,9 @@ The runtime owns semantics; the host owns placement and substrate. `createActorC
 | `ports.facets` | A `FacetHost`: place a child container, abort it, copy or delete its storage. |
 | `ports.timer` | `now()` and `afterDelay()`, captured below any installed actor scope. |
 | `ports.fetch` | Optional global outbound. Absent means `fetch` refuses by name, as a Worker with `globalOutbound: null` does. |
+| `ports.hibernation` | Optional mirror callbacks for accepted sockets, attachment bytes, auto-response changes, and closure. Omit it when the host never rebuilds a live socket placement. |
+| `webSockets` | Socket references and mirrored tags/attachments to register before the new instance constructor runs. |
+| `gateHooks` | Optional input/output gate instrumentation for an embedding host. |
 | `facet` | Present when constructing a local child: its id, depth, and the root-owned `FacetTree`. |
 
 The lifecycle:
@@ -185,6 +188,7 @@ The lifecycle:
 4. Use `container.run(fn, signal?)` for events that are not method calls: a WebSocket frame, a host callback. Its signal likewise stops only a queued event, not one already running.
 5. Reach the platform through `container.globals` (or install it with `installActorScope`). For a host-provided promise an actor must await, wrap it once in `container.awaitIo()`.
 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.
 
 For a standard Durable Object binding, call
 `createDurableObjectNamespace(uniqueKey, channel)` and put the result in `env`
@@ -221,7 +225,25 @@ Construct one `AlarmScheduler` per namespace over a `SqlDatabase` of its own. It
 
 On workerd every awaitable thing is an io-context primitive, so "resuming from an await re-enters with a fresh input lock" never needs saying. Here it does. A raw `setTimeout` resolves a promise the runtime does not own; the continuation resumes with an empty invocation stack and the next `ctx.storage` call throws `no input lock available in this context`. That is by design — the alternative is a continuation that silently writes outside the gate.
 
-`container.globals` is the complete gated set, bound to that container: `setTimeout`/`clearTimeout`/`setInterval`/`clearInterval` capture the critical section when armed and re-enter when fired; `scheduler.wait()` and `scheduler.yield()` resume under the actor; `fetch()` waits for output locks and releases the input gate while in flight; `crypto` re-enters on async completion; accepted WebSocket frames enter through the captured context. Install it as the worker's globals (`installActorScope`) when one worker hosts one root, or hand it to application code explicitly when it must not.
+`container.globals` is the complete gated set, bound to that container: `setTimeout`/`clearTimeout`/`setInterval`/`clearInterval` capture the critical section when armed and re-enter when fired; `scheduler.wait()` and `scheduler.yield()` resume under the actor; `fetch()` waits for output locks and releases the input gate while in flight; `crypto` re-enters on async completion; and `WebSocketPair` creates runtime-owned socket halves. Install it as the worker's globals (`installActorScope`) when one worker hosts one root, or hand it to application code explicitly when it must not.
+
+### Hibernatable WebSockets
+
+`ctx.acceptWebSocket(socket, tags)` enables class-method dispatch and the full
+Workers state API: `getWebSockets`, `getTags`, attachments, auto-response pairs
+and timestamps, and the hibernatable event timeout. The runtime works without a
+hibernation port for hosts that keep a container alive.
+
+An evicting host implements `ports.hibernation` as a mirror. It retains the same
+raw socket reference plus copied tags and attachment bytes, drops the old
+placement, and supplies that snapshot as `webSockets` on the replacement. The
+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.
+
+`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.
 
 Actor bundles can also install `doRuntimeAwaitTransform()` from `@mcp-b/do-runtime/vite`. A production build checks the final module graph and fails with transformed/total counts for any included module with an uncovered await; the development transform warns once per module if a transformed await reaches its fail-open path without an actor lock.
 
@@ -231,14 +253,15 @@ The browser cannot reproduce every workerd facility. Where it cannot, the runtim
 
 | Area | Contract here |
 | --- | --- |
-| Hibernatable WebSockets | Unsupported; named methods throw. Use memory-only sockets and reconnect. |
 | Cloudflare point-in-time recovery and read replication | Unsupported by local SQLite; named methods throw. Bookmarks are development counters, not recovery points. |
 | Actor-class stub serialization | Throws; needs workerd's serializer and channel tokens. |
 | Module-scope `waitUntil`, `cache`, `abortIsolate`, Workers RPC stub constructors | Named `cloudflare:workers` boundaries throw. |
 | `DurableObjectState.abort()` | Breaks later storage and re-entry; cannot synchronously terminate the calling JavaScript slice. |
 | Stored value wire bytes | Browser-safe versioned structured-clone encoding rather than V8's private format; public value types align and legacy JSON rows remain readable. |
 | SQL row counters | Local `rowsRead`/`rowsWritten`, including `sql.ingest()`, use returned rows and SQLite changes; workerd uses unavailable libsql billing counters. |
-| Reserved SQL names | `_cf_` detected from tokenized SQL text, which can reject more than workerd's authorizer. |
+| Reserved SQL names | `_cf_` detected from tokenized SQL text, which can reject more than workerd's authorizer. `ANALYZE` on a reserved table is refused where workerd allows it. |
+| Authorizer-only SQL forms | `ATTACH`, `DETACH`, the temp-schema creations (both `CREATE TEMP …` and the `temp.` qualifier), `VACUUM`, and virtual-table modules outside upstream's four (`fts5`, `fts5vocab`, `rtree`, `rtree_i32`) are refused from the leading keyword, with workerd's own messages. These reach the authorizer's own decisions — action codes and its temp-schema rule — rather than `SqlStorageRegulator` callbacks, so porting the regulator did not carry them. The refused and allowed forms are matched through SQLite's identifier quoting, whitespace or none. `EXPLAIN` in front of a refused form still compiles here, where workerd's authorizer refuses it. |
+| SQL function allowlist | Not enforced. Workerd's authorizer denies any function outside its 138-name `ALLOWED_SQLITE_FUNCTIONS` list; this runtime allows every function the backend compiled, including build-detail readers such as `sqlite_version()` and `sqlite_source_id()`. |
 | PRAGMA allowlist | Workerd's allowlist enforced from tokenized SQL text. A `pragma_*` table-valued function with a string or bound argument is authorized by pragma name only, where workerd's authorizer also sees the resolved argument; the pinned conformance row is the contract. |
 | Node SQLite length limit | Bound and returned strings and blobs are capped at 4 MiB; `node:sqlite` cannot cap an unreturned SQL-computed value. The browser backend uses SQLite's native limit. |
 | Response BYOB readers | Refused; their continuation cannot be re-gated. Use a default reader or `arrayBuffer()`. |

package/dist/chunks/{io-context-RmmjNtwm.js → io-context-BBgKEsdR.js}

@@ -995,13 +995,16 @@ var TimeoutManager = class {
 		const criticalSection = ctx.getCriticalSection();
 		const wake = new AbortController();
 		state.armed = wake;
-		const fired = this.#timer.afterDelay(state.params.msDelay, wake.signal).then(async () => {
+		const canceled = new Promise((resolve) => {
+			wake.signal.addEventListener("abort", () => resolve(), { once: true });
+		});
+		const fired = Promise.race([this.#timer.afterDelay(state.params.msDelay, wake.signal).then(async () => {
 			if (state.isCanceled) return;
 			state.armed = void 0;
 			await this.#fire(ctx, id, state, criticalSection);
 		}, (exception) => {
 			if (!state.isCanceled) throw exception;
-		});
+		}), canceled]);
 		ctx.addWaitUntil(fired);
 	}
 	/** ← the body of the `.then` at `io-context.c++:759-816`, which is one `context.run`. */
@@ -1042,6 +1045,9 @@ var TaskSet = class {
 		});
 		this.#tasks.add(task);
 	}
+	size() {
+		return this.#tasks.size;
+	}
 	/** ← `kj::TaskSet::onEmpty()`. Re-checks, since a task can add another. */
 	async onEmpty() {
 		while (this.#tasks.size > 0) await Promise.all([...this.#tasks]);
@@ -1281,6 +1287,9 @@ var IoContext = class {
 	waitUntilStatus() {
 		return this.#waitUntilStatus?.exception;
 	}
+	waitUntilTaskCount() {
+		return this.#waitUntilTasks.size();
+	}
 	/**
 	* ← `IncomingRequest::drain()`, actor branch. "For actors, all promises are canceled on
 	* actor shutdown, not on a fixed timeout, because work doesn't necessarily happen on a
@@ -1500,4 +1509,4 @@ var IoContext = class {
 //#endregion
 export { hasUserErrorDetail as a, setUserErrorDetail as c, tryCurrentSlice as d, CanceledError as f, captureGateStack as i, tryCurrentContinuation as l, OutputGate as m, IoContext as n, isExceptionFromInputGateBroken as o, InputGate as p, atCheckpointEnd as r, requireInputLock as s, BrokenActorError as t, tryCurrentIoContext as u };
 
-//# sourceMappingURL=io-context-RmmjNtwm.js.map
+//# sourceMappingURL=io-context-BBgKEsdR.js.map