@mcp-b/do-runtime 0.6.0 → 0.7.0

package/dist/src/api/web-socket.d.ts

@@ -15,12 +15,18 @@ export interface RawWebSocket {
     binaryType?: string;
 }
 export interface HibernationHost {
+    /** Retained auto-response configuration, restored before actor construction. */
+    readonly autoResponsePair?: {
+        request: string;
+        response: string;
+    } | null;
     accepted(socket: RawWebSocket, tags: readonly string[]): void;
     attachment(socket: RawWebSocket, bytes: Uint8Array | null): void;
     autoResponse(pair: {
         request: string;
         response: string;
     } | null): void;
+    autoResponseTimestamp?(socket: RawWebSocket, timestamp: number): void;
     closed(socket: RawWebSocket): void;
 }
 export type RehydratedWebSocket = {

package/dist/src/browser/alarm-coordinator.d.ts

@@ -0,0 +1,46 @@
+type LooseRecord = Record<string, unknown>;
+export type BrowserAlarmProjection = {
+    readonly generation: number;
+    readonly when: number | null;
+} & LooseRecord;
+export type BrowserAlarmDelivery = {
+    readonly generation: number;
+    readonly retryCount: number;
+    readonly wake: number;
+} & LooseRecord;
+export type BrowserAlarmTransportJournal = {
+    readonly delivery: BrowserAlarmDelivery | null;
+    readonly projection: BrowserAlarmProjection;
+} & LooseRecord;
+export interface BrowserAlarmTransportStore {
+    load(): Promise<BrowserAlarmTransportJournal | null>;
+    save(journal: BrowserAlarmTransportJournal): Promise<void>;
+}
+export interface BrowserPhysicalAlarm {
+    clear(): Promise<void>;
+    create(when: number): Promise<void>;
+}
+export type BrowserAlarmCoordinatorOptions = {
+    deliver(scheduledTime: number): Promise<BrowserAlarmProjection>;
+    now?: () => number;
+    physical: BrowserPhysicalAlarm;
+    store: BrowserAlarmTransportStore;
+};
+/**
+ * Projects a logical namespace alarm onto one crash-prone browser alarm.
+ *
+ * `AlarmScheduler` remains authoritative for actor delivery and retries. This
+ * coordinator journals the physical hop so a browser background worker can be
+ * stopped between any two awaited operations without losing the next wake.
+ */
+export declare class BrowserAlarmCoordinator {
+    #private;
+    private readonly options;
+    constructor(options: BrowserAlarmCoordinatorOptions);
+    project(projection: BrowserAlarmProjection): Promise<void>;
+    /** Repairs an acknowledged physical operation interrupted by browser suspension. */
+    reconcile(): Promise<void>;
+    fire(scheduledTime: number): Promise<BrowserAlarmProjection | null>;
+}
+export declare function parseBrowserAlarmTransportJournal(value: unknown): BrowserAlarmTransportJournal | null;
+export {};

package/dist/src/browser/message-port-websocket.d.ts

@@ -0,0 +1,62 @@
+import type { RawWebSocket } from "../api/web-socket.js";
+import type { UpgradeWebSocket } from "../browser.js";
+export type MessagePortWebSocketData = string | ArrayBuffer | ArrayBufferView;
+export type MessagePortWebSocketWireMessage = {
+    readonly type: "message";
+    readonly data: MessagePortWebSocketData;
+} | {
+    readonly type: "close";
+    readonly code: number;
+    readonly reason: string;
+};
+/** One WebSocket-shaped endpoint backed by one dedicated MessagePort. */
+export declare class MessagePortWebSocket extends EventTarget implements RawWebSocket {
+    #private;
+    readonly url: string;
+    private readonly port;
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    readonly CONNECTING = 0;
+    readonly OPEN = 1;
+    readonly CLOSING = 2;
+    readonly CLOSED = 3;
+    binaryType: BinaryType;
+    bufferedAmount: number;
+    extensions: string;
+    protocol: string;
+    readyState: number;
+    onopen: ((event: Event) => void) | null;
+    onmessage: ((event: MessageEvent<MessagePortWebSocketData>) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    onerror: ((event: Event) => void) | null;
+    constructor(url: string, port: MessagePort, autoOpen?: boolean);
+    send(data: MessagePortWebSocketData): void;
+    close(code?: number, reason?: string): void;
+    accept(_options?: {
+        allowHalfOpen?: boolean;
+    }): void;
+    open(): void;
+    /** End a socket whose physical host disappeared without notifying that host. */
+    protected disconnect(code?: number, reason?: string): void;
+}
+export interface MessagePortWebSocket {
+    addEventListener(type: "message", listener: (event: MessageEvent<MessagePortWebSocketData>) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: "close", listener: (event: CloseEvent) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: "error" | "open", listener: (event: Event) => void, options?: boolean | AddEventListenerOptions): void;
+    addEventListener(type: string, listener: EventListenerOrEventListenerObject | null, options?: boolean | AddEventListenerOptions): void;
+}
+/** Connect two accepted socket endpoints and open the MessagePort side. */
+export declare function bridgeWebSocket(socket: UpgradeWebSocket, bridge: MessagePortWebSocket): void;
+export type MessagePortWebSocketConstructor = {
+    new (url: string | URL, protocols?: string | string[]): MessagePortWebSocket;
+    readonly CONNECTING: 0;
+    readonly OPEN: 1;
+    readonly CLOSING: 2;
+    readonly CLOSED: 3;
+};
+/** A browser WebSocket constructor whose sockets cross one broker MessagePort. */
+export declare function createMessagePortWebSocketConstructor(port: MessagePort): MessagePortWebSocketConstructor;
+/** Serve brokered MessagePort sockets from real in-worker socket endpoints. */
+export declare function serveMessagePortWebSockets(port: MessagePort, connect: (url: string) => Promise<UpgradeWebSocket>): () => void;

package/dist/src/browser/offscreen-document.d.ts

@@ -0,0 +1,17 @@
+export type OffscreenDocumentAdapter = {
+    exists(): Promise<boolean>;
+    create(): Promise<void>;
+    close(): Promise<void>;
+    isOccupiedError(error: unknown): boolean;
+};
+/**
+ * Keeps one browser offscreen document alive across concurrent callers and a
+ * stale, unlisted document slot. Readiness and application policy stay with
+ * the embedding host.
+ */
+export declare class OffscreenDocumentCoordinator {
+    #private;
+    private readonly adapter;
+    constructor(adapter: OffscreenDocumentAdapter);
+    ensure(): Promise<void>;
+}

package/dist/src/browser.d.ts

@@ -0,0 +1,15 @@
+import { type RawWebSocket } from "./api/web-socket.js";
+export type UpgradeWebSocket = EventTarget & RawWebSocket & {
+    accept(): void;
+    readonly readyState: number;
+};
+type CloneableRequest = {
+    readonly headers: Headers;
+    clone(): CloneableRequest;
+};
+/** Install the Request/Response half of browser-hosted WebSocket upgrades. */
+export declare function installWebSocketUpgradeGlobals(): void;
+export declare function upgradeWebSocket(response: Response): UpgradeWebSocket | undefined;
+/** Preserve the upgrade signal across browser `Request.clone()` calls. */
+export declare function withWebSocketUpgrade<T extends CloneableRequest>(request: T): T;
+export {};

package/dist/src/index.d.ts

@@ -53,6 +53,8 @@ export type { Module as SourceModule, ModuleContent, ModulesSource, WorkerSource
  */
 export type { ActorContainer, ActorContainerOptions, ActorEntry, ActorPorts, HibernationHost, FacetHandle, FacetHost, FacetId, FacetStartRequest, FacetTree, } from "./server/actor-container.js";
 export { createActorContainer, FACET_ALARM_UNIMPLEMENTED_MESSAGE, noFacets, } from "./server/actor-container.js";
+export type { HibernationAutoResponse } from "./server/hibernation-mirror.js";
+export { HibernationMirror } from "./server/hibernation-mirror.js";
 export type { ActorChannelFactory, GlobalActorRequest } from "./api/actor.js";
 export { createDurableObjectNamespace } from "./server/actor-namespace.js";
 export { ACTOR_CLASS_SERIALIZATION_UNIMPLEMENTED_MESSAGE } from "./api/actor.js";

package/dist/src/server/hibernation-mirror.d.ts

@@ -0,0 +1,18 @@
+import type { HibernationHost, RawWebSocket, RehydratedWebSocket } from "../api/web-socket.js";
+export type HibernationAutoResponse = {
+    request: string;
+    response: string;
+};
+/** In-memory socket state shared by embedders that replace live actor containers. */
+export declare class HibernationMirror implements HibernationHost {
+    #private;
+    constructor(rehydrated?: readonly RehydratedWebSocket[], autoResponsePair?: HibernationAutoResponse | null);
+    get autoResponsePair(): HibernationAutoResponse | null;
+    accepted(socket: RawWebSocket, tags: readonly string[]): void;
+    attachment(socket: RawWebSocket, bytes: Uint8Array | null): void;
+    autoResponse(pair: HibernationAutoResponse | null): void;
+    /** Also called by a host that answers a ping while no actor container is live. */
+    autoResponseTimestamp(socket: RawWebSocket, timestamp: number): void;
+    closed(socket: RawWebSocket): void;
+    snapshot(): RehydratedWebSocket[];
+}

package/docs/assets/extension-agent-runtime.svg

@@ -0,0 +1,178 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1400" height="760" viewBox="0 0 1400 760" role="img" aria-labelledby="title description">
+  <title id="title">A local agent running inside a browser extension</title>
+  <desc id="description">A browser window with an extension popup open over an abstract, persistent agent workspace.</desc>
+  <defs>
+    <linearGradient id="backdrop" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#080b16" />
+      <stop offset="0.52" stop-color="#11162a" />
+      <stop offset="1" stop-color="#0a101d" />
+    </linearGradient>
+    <linearGradient id="viewport" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#12182d" />
+      <stop offset="0.48" stop-color="#0e1830" />
+      <stop offset="1" stop-color="#071622" />
+    </linearGradient>
+    <radialGradient id="violet-haze" cx="0" cy="0" r="1" gradientTransform="translate(491 391) rotate(20) scale(365 290)" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#7c3aed" stop-opacity="0.34" />
+      <stop offset="0.55" stop-color="#4f46e5" stop-opacity="0.11" />
+      <stop offset="1" stop-color="#4f46e5" stop-opacity="0" />
+    </radialGradient>
+    <radialGradient id="teal-haze" cx="0" cy="0" r="1" gradientTransform="translate(745 546) rotate(-14) scale(414 236)" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#2dd4bf" stop-opacity="0.24" />
+      <stop offset="1" stop-color="#2dd4bf" stop-opacity="0" />
+    </radialGradient>
+    <linearGradient id="agent" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#a78bfa" />
+      <stop offset="0.5" stop-color="#6366f1" />
+      <stop offset="1" stop-color="#2563eb" />
+    </linearGradient>
+    <linearGradient id="thread" x1="0" y1="0" x2="1" y2="0">
+      <stop stop-color="#22d3ee" stop-opacity="0" />
+      <stop offset="0.28" stop-color="#2dd4bf" />
+      <stop offset="0.7" stop-color="#60a5fa" />
+      <stop offset="1" stop-color="#818cf8" stop-opacity="0" />
+    </linearGradient>
+    <linearGradient id="popup" x1="0" y1="0" x2="0" y2="1">
+      <stop stop-color="#ffffff" />
+      <stop offset="1" stop-color="#f5f7fb" />
+    </linearGradient>
+    <pattern id="grid" width="34" height="34" patternUnits="userSpaceOnUse">
+      <path d="M34 0H0V34" fill="none" stroke="#94a3b8" stroke-opacity="0.075" />
+    </pattern>
+    <clipPath id="window-clip">
+      <rect x="100" y="62" width="1200" height="636" rx="28" />
+    </clipPath>
+    <filter id="window-shadow" x="-20%" y="-20%" width="140%" height="155%">
+      <feDropShadow dx="0" dy="30" stdDeviation="34" flood-color="#000000" flood-opacity="0.42" />
+    </filter>
+    <filter id="popup-shadow" x="-35%" y="-25%" width="170%" height="170%">
+      <feDropShadow dx="0" dy="22" stdDeviation="24" flood-color="#020617" flood-opacity="0.38" />
+    </filter>
+    <filter id="orb-glow" x="-100%" y="-100%" width="300%" height="300%">
+      <feGaussianBlur stdDeviation="18" result="blur" />
+      <feMerge>
+        <feMergeNode in="blur" />
+        <feMergeNode in="SourceGraphic" />
+      </feMerge>
+    </filter>
+    <filter id="line-glow" x="-20%" y="-250%" width="140%" height="600%">
+      <feGaussianBlur stdDeviation="6" result="blur" />
+      <feMerge>
+        <feMergeNode in="blur" />
+        <feMergeNode in="SourceGraphic" />
+      </feMerge>
+    </filter>
+  </defs>
+
+  <rect width="1400" height="760" rx="32" fill="url(#backdrop)" />
+  <circle cx="170" cy="126" r="230" fill="#4f46e5" fill-opacity="0.1" />
+  <circle cx="1254" cy="654" r="280" fill="#0d9488" fill-opacity="0.08" />
+
+  <g filter="url(#window-shadow)">
+    <rect x="100" y="62" width="1200" height="636" rx="28" fill="#f8fafc" />
+  </g>
+
+  <g clip-path="url(#window-clip)">
+    <!-- Browser chrome -->
+    <rect x="100" y="62" width="1200" height="94" fill="#eef1f6" />
+    <circle cx="132" cy="92" r="6" fill="#ef6a67" />
+    <circle cx="154" cy="92" r="6" fill="#e6b84a" />
+    <circle cx="176" cy="92" r="6" fill="#58b96f" />
+
+    <path d="M226 75H456A15 15 0 0 1 471 90V113H211V90A15 15 0 0 1 226 75Z" fill="#ffffff" />
+    <circle cx="238" cy="94" r="7" fill="#6d5dfc" />
+    <rect x="255" y="89" width="108" height="10" rx="5" fill="#cbd2df" />
+    <path d="M443 89 451 97M451 89 443 97" stroke="#9ca7b9" stroke-width="1.6" stroke-linecap="round" />
+
+    <rect x="100" y="113" width="1200" height="43" fill="#ffffff" />
+    <path d="M132 134H148M132 134 139 127M132 134 139 141" fill="none" stroke="#68758b" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+    <path d="M175 134H191M191 134 184 127M191 134 184 141" fill="none" stroke="#c2c9d4" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+    <path d="M219 128A9 9 0 1 0 222 140M219 128 225 127 224 133" fill="none" stroke="#68758b" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" />
+    <rect x="248" y="120" width="770" height="28" rx="14" fill="#eef1f5" />
+    <path d="M270 131V128A4 4 0 0 1 278 128V131M268 131H280V140H268Z" fill="none" stroke="#8d98aa" stroke-width="1.25" stroke-linejoin="round" />
+    <rect x="292" y="130" width="155" height="8" rx="4" fill="#c9d0dc" />
+
+    <!-- The highlighted extension button anchors the popup to the browser. -->
+    <circle cx="1128" cy="134" r="18" fill="#ece9ff" />
+    <path d="M1122 125H1128V130A4 4 0 1 1 1134 134V143H1125V139A4 4 0 1 1 1122 133Z" fill="#6857e5" />
+    <circle cx="1180" cy="134" r="3" fill="#68758b" />
+    <circle cx="1191" cy="134" r="3" fill="#68758b" />
+    <circle cx="1202" cy="134" r="3" fill="#68758b" />
+
+    <!-- An ordinary web page, kept intentionally abstract. -->
+    <rect x="100" y="156" width="1200" height="542" fill="url(#viewport)" />
+    <rect x="100" y="156" width="1200" height="542" fill="url(#grid)" />
+    <rect x="100" y="156" width="1200" height="542" fill="url(#violet-haze)" />
+    <rect x="100" y="156" width="1200" height="542" fill="url(#teal-haze)" />
+
+    <rect x="136" y="193" width="52" height="468" rx="18" fill="#151d33" stroke="#ffffff" stroke-opacity="0.07" />
+    <circle cx="162" cy="222" r="10" fill="#6d5dfc" />
+    <circle cx="162" cy="282" r="6" fill="#68758b" />
+    <circle cx="162" cy="323" r="6" fill="#68758b" />
+    <circle cx="162" cy="364" r="6" fill="#68758b" />
+    <rect x="154" y="619" width="16" height="16" rx="5" fill="#29334c" />
+
+    <rect x="226" y="201" width="228" height="12" rx="6" fill="#dbe4f4" fill-opacity="0.64" />
+    <rect x="226" y="229" width="138" height="8" rx="4" fill="#9aa9c5" fill-opacity="0.28" />
+
+    <!-- One continuous thread remains while the surrounding surface fades. -->
+    <path d="M242 534C328 534 337 473 407 473S502 552 579 552 663 453 746 453 819 489 881 489" fill="none" stroke="#0b2235" stroke-width="18" stroke-linecap="round" />
+    <path d="M242 534C328 534 337 473 407 473S502 552 579 552 663 453 746 453 819 489 881 489" fill="none" stroke="url(#thread)" stroke-width="4" stroke-linecap="round" filter="url(#line-glow)" />
+    <circle cx="309" cy="513" r="4" fill="#5eead4" />
+    <circle cx="579" cy="552" r="5" fill="#67e8f9" />
+    <circle cx="800" cy="471" r="4" fill="#93c5fd" />
+
+    <!-- The agent is a presence, not another architecture box. -->
+    <circle cx="515" cy="385" r="112" fill="#5b4be8" fill-opacity="0.09" />
+    <circle cx="515" cy="385" r="82" fill="#5b4be8" fill-opacity="0.13" />
+    <circle cx="515" cy="385" r="53" fill="url(#agent)" filter="url(#orb-glow)" />
+    <path d="M492 386C502 374 528 374 538 386M498 403C510 413 522 413 534 403" fill="none" stroke="#ffffff" stroke-opacity="0.9" stroke-width="4" stroke-linecap="round" />
+    <circle cx="496" cy="370" r="5" fill="#ffffff" fill-opacity="0.92" />
+    <circle cx="534" cy="370" r="5" fill="#ffffff" fill-opacity="0.92" />
+    <circle cx="409" cy="335" r="8" fill="#2dd4bf" fill-opacity="0.9" />
+    <circle cx="648" cy="314" r="7" fill="#60a5fa" fill-opacity="0.82" />
+    <circle cx="680" cy="407" r="4" fill="#c4b5fd" fill-opacity="0.8" />
+
+    <!-- A quiet alarm pulse reads as wake-up without becoming a diagram. -->
+    <circle cx="746" cy="453" r="29" fill="#f97316" fill-opacity="0.07" stroke="#fb923c" stroke-opacity="0.28" />
+    <circle cx="746" cy="453" r="13" fill="#fb923c" fill-opacity="0.16" stroke="#fdba74" stroke-width="2" />
+    <path d="M746 445V453L752 457" fill="none" stroke="#fed7aa" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+
+    <rect x="226" y="608" width="512" height="10" rx="5" fill="#33405a" fill-opacity="0.75" />
+    <rect x="226" y="632" width="362" height="8" rx="4" fill="#29364f" fill-opacity="0.68" />
+  </g>
+
+  <!-- Extension popup -->
+  <g filter="url(#popup-shadow)">
+    <path d="M1128 151 1142 169H1114Z" fill="#ffffff" />
+    <rect x="892" y="165" width="332" height="438" rx="24" fill="url(#popup)" />
+  </g>
+  <rect x="893" y="166" width="330" height="436" rx="23" fill="none" stroke="#d9dfeb" />
+
+  <circle cx="935" cy="210" r="17" fill="url(#agent)" />
+  <path d="M928 211C932 206 938 206 942 211" fill="none" stroke="#ffffff" stroke-width="2" stroke-linecap="round" />
+  <rect x="966" y="199" width="95" height="10" rx="5" fill="#182033" />
+  <rect x="966" y="218" width="56" height="7" rx="3.5" fill="#a8b1c1" />
+  <circle cx="1183" cy="210" r="6" fill="#34d399" />
+  <circle cx="1183" cy="210" r="11" fill="none" stroke="#34d399" stroke-opacity="0.2" />
+  <path d="M916 249H1200" stroke="#e4e8f0" />
+
+  <text x="1058" y="357" text-anchor="middle" fill="#121827" font-family="system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif" font-size="104" font-weight="690" letter-spacing="-6">21</text>
+  <circle cx="1058" cy="395" r="5" fill="#6366f1" />
+  <circle cx="1075" cy="395" r="5" fill="#d8dce6" />
+  <circle cx="1041" cy="395" r="5" fill="#d8dce6" />
+
+  <rect x="924" y="439" width="268" height="70" rx="20" fill="#111827" />
+  <circle cx="974" cy="474" r="18" fill="#262f43" />
+  <path d="M966 474H982M974 466V482" stroke="#ffffff" stroke-width="2.6" stroke-linecap="round" />
+  <path d="M1019 474H1117" stroke="#465269" stroke-width="4" stroke-linecap="round" />
+  <path d="M1019 474C1037 474 1040 459 1055 459S1076 488 1092 488 1103 474 1117 474" fill="none" stroke="url(#thread)" stroke-width="3" stroke-linecap="round" />
+  <circle cx="1154" cy="474" r="18" fill="#fff0e6" />
+  <circle cx="1154" cy="474" r="8" fill="none" stroke="#f97316" stroke-width="2" />
+  <path d="M1154 469V474L1158 477" fill="none" stroke="#f97316" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" />
+
+  <rect x="924" y="538" width="88" height="8" rx="4" fill="#d5dae5" />
+  <rect x="924" y="558" width="206" height="8" rx="4" fill="#e2e6ed" />
+  <circle cx="1173" cy="552" r="17" fill="#e9e7ff" />
+  <path d="M1166 553 1171 558 1181 546" fill="none" stroke="#6657de" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round" />
+</svg>

package/docs/migrations.md

@@ -0,0 +1,235 @@
+# How to migrate Durable Object and Agent data
+
+Use the same application migration mechanism on Cloudflare and on
+`@mcp-b/do-runtime`. This package does not add an application migration registry.
+
+Start by identifying what changed:
+
+| Change | Migration owner | What to do |
+| --- | --- | --- |
+| Add, rename, transfer, or delete a Durable Object class on Cloudflare | Cloudflare deployment configuration | Update Wrangler's `exports`, or the legacy `migrations` array if the Worker still uses it. |
+| Change an application SQL table | The application | Generate and run a Drizzle migration in the actor constructor. |
+| Change the JSON shape stored by `Agent.state` | The application | Version the state and override `migratePersistedState()` in the Rook Agents SDK fork. |
+| Change an Agents SDK internal `cf_agents_*` table | The Agents SDK | Upgrade the SDK. Its `_ensureSchema()` runs automatically. |
+| Change a `do-runtime` internal `_cf_*` table | `do-runtime` | Upgrade this package. Runtime storage migration runs before actor construction. |
+
+## Understand the Wrangler declaration
+
+Wrangler's Durable Object configuration manages class and namespace lifecycle. It
+does not run application SQL or transform `Agent.state`.
+
+For a new Worker, follow Cloudflare's current `exports` form:
+
+```jsonc
+{
+  "$schema": "./node_modules/wrangler/config-schema.json",
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "ROOK_AGENT",
+        "class_name": "RookAgent"
+      }
+    ]
+  },
+  "exports": {
+    "RookAgent": {
+      "type": "durable-object",
+      "storage": "sqlite"
+    }
+  }
+}
+```
+
+An existing Worker may still have the legacy form:
+
+```jsonc
+{
+  "durable_objects": {
+    "bindings": [
+      {
+        "name": "ROOK_AGENT",
+        "class_name": "RookAgent"
+      }
+    ]
+  },
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["RookAgent"]
+    }
+  ]
+}
+```
+
+Keep the legacy history unless you intentionally follow Cloudflare's conversion
+guide. A Worker cannot use `exports` and `migrations` together.
+
+The legacy `tag` orders class-lifecycle changes. It is not an application schema
+version and does not point at Drizzle migrations. Adding a SQL column or changing
+a TypeScript state type does not require another Wrangler entry.
+
+A local `do-runtime` host has no Wrangler deployment. The host registers the
+class in `ActorContainerOptions.exports` and constructs its namespace with a
+stable `uniqueKey`. Never change that key for an existing namespace: it is part
+of every actor ID and therefore determines which storage the actor opens.
+
+Cloudflare reference:
+
+- [Durable Object class exports](https://developers.cloudflare.com/durable-objects/reference/durable-objects-migrations/)
+- [Legacy Durable Object class migrations](https://developers.cloudflare.com/durable-objects/reference/durable-object-class-migrations-legacy/)
+
+## Migrate application SQL with Drizzle
+
+Use Drizzle's Durable Object driver and migrator for tables owned by Rook. The
+same constructor pattern runs on Cloudflare and on `do-runtime`.
+
+1. Change the Drizzle schema.
+2. Run the repository's `drizzle-kit generate` command.
+3. Review and commit the generated SQL and migration journal.
+4. Import that migration bundle into the actor.
+5. Run `migrate()` inside `blockConcurrencyWhile()` so no event can observe a
+   partially initialized schema.
+
+```ts
+import { Agent } from "agents";
+import { drizzle, type DrizzleSqliteDODatabase } from "drizzle-orm/durable-sqlite";
+import { migrate } from "drizzle-orm/durable-sqlite/migrator";
+import migrations from "../drizzle/migrations";
+
+export class RookAgent extends Agent<Env> {
+  readonly db: DrizzleSqliteDODatabase;
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.db = drizzle(ctx.storage);
+
+    void ctx.blockConcurrencyWhile(async () => {
+      await migrate(this.db, migrations);
+    });
+  }
+}
+```
+
+Drizzle records applied migrations in each actor's database. Every actor runs the
+constructor on its next wake, applies only missing migrations, and then accepts
+events. Do not use schema push as a production migration strategy, and do not
+edit or reorder a migration after shipping it.
+
+The executable proof for this runtime is
+[`src/drizzle-migrations.test.ts`](../src/drizzle-migrations.test.ts). It starts
+an actor with one schema generation, preserves its data across eviction, starts
+the same actor with a second generation, and verifies the pending migration runs
+once.
+
+Upstream references:
+
+- [Cloudflare: initialize storage and run migrations in the constructor](https://developers.cloudflare.com/durable-objects/best-practices/rules-of-durable-objects/#initialize-storage-and-run-migrations-in-the-constructor)
+- [Drizzle: Cloudflare Durable Objects SQLite](https://orm.drizzle.team/docs/sqlite/connect-cloudflare-do)
+
+## Migrate persisted `Agent.state`
+
+`Agent.state` is one JSON value stored in the Agents SDK's `cf_agents_state`
+table. Drizzle does not know its application shape, and `initialState` applies
+only when no persisted state exists.
+
+Give the state an integer version and handle every shipped shape. The
+`migratePersistedState()` hook is currently supplied by the Rook Agents SDK fork;
+it is not part of upstream Agents 0.22.
+
+```ts
+import { Agent } from "agents";
+
+type RookState = {
+  stateVersion: 1;
+  count: number;
+  label: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export class RookAgent extends Agent<Env, RookState> {
+  override initialState: RookState = {
+    stateVersion: 1,
+    count: 0,
+    label: "current"
+  };
+
+  protected override migratePersistedState(value: unknown): RookState {
+    if (!isRecord(value) || typeof value.count !== "number") {
+      throw new TypeError("invalid persisted Rook state");
+    }
+
+    const version = value.stateVersion ?? 0;
+    if (version === 0) {
+      return {
+        stateVersion: 1,
+        count: value.count,
+        label: typeof value.label === "string" ? value.label : "migrated"
+      };
+    }
+
+    if (version === 1 && typeof value.label === "string") {
+      return value as RookState;
+    }
+
+    throw new TypeError(`unsupported persisted Rook state version: ${String(version)}`);
+  }
+}
+```
+
+The hook runs when existing state is first hydrated, before the value is exposed
+to the Agent or sent to a client. Returning a changed object persists the new
+value without treating boot repair as a user update. Returning the same object
+by reference is the no-op path. If migration throws, the stored row remains
+unchanged so a fixed release can retry it.
+
+Keep these constraints:
+
+- Treat the input as `unknown`; TypeScript types do not validate stored JSON.
+- Retain every migration path for a state shape that reached users.
+- Validate the current shape before returning it.
+- Do not call `setState()` from the migration hook.
+- Do not replace invalid persisted data with `initialState` automatically.
+
+Cloudflare documents the persistence behavior and the fact that existing Agents
+load stored state rather than merging `initialState`:
+
+- [Store and sync Agent state](https://developers.cloudflare.com/agents/runtime/lifecycle/state/)
+
+## Leave package-owned schemas alone
+
+The Agents SDK calls its versioned `_ensureSchema()` during construction. Rook
+must not create or alter `cf_agents_*` tables itself.
+
+`do-runtime` opens and versions its own `_cf_*` storage before constructing the
+actor. Application SQL cannot read or write the runtime's `PRAGMA user_version`,
+matching workerd's pragma restrictions. Rook must not create or alter `_cf_*`
+tables either.
+
+## Verify an upgrade before release
+
+For every persisted shape that has shipped:
+
+1. Start the previous application version and write representative data.
+2. Destroy the actor instance without deleting its storage.
+3. Start the new version over the same storage.
+4. Verify SQL rows and `Agent.state` were preserved and transformed.
+5. Recreate the actor once more and verify every migration is now a no-op.
+6. Inject an invalid or future state version and verify the original data remains
+   available for recovery.
+
+Run the package's focused checks with:
+
+```sh
+pnpm exec vitest run --config vitest.unit.config.ts \
+  src/drizzle-migrations.test.ts \
+  src/util/sqlite-migrations.test.ts
+
+pnpm --filter do-runtime-example-extension e2e
+```
+
+The extension end-to-end test seeds an old unversioned `Agent.state`, destroys
+the browser host, and verifies the replacement persists the migrated value before
+a newly connected client sees it.