opencodekit 0.15.4 → 0.15.5

package/dist/template/.opencode/skill/cloudflare/references/do-storage/patterns.md

@@ -0,0 +1,112 @@
+# DO Storage Patterns & Best Practices
+
+## Schema Migration
+
+```typescript
+export class MyDurableObject extends DurableObject {
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.sql = ctx.storage.sql;
+    this.sql.exec(`CREATE TABLE IF NOT EXISTS _meta(key TEXT PRIMARY KEY, value TEXT)`);
+    const ver = this.sql.exec("SELECT value FROM _meta WHERE key = 'schema_version'").toArray()[0]?.value || "0";
+    if (ver === "0") this.sql.exec(`CREATE TABLE users(id INTEGER PRIMARY KEY, name TEXT); INSERT OR REPLACE INTO _meta VALUES ('schema_version', '1')`);
+    if (ver === "1") this.sql.exec(`ALTER TABLE users ADD COLUMN email TEXT; UPDATE _meta SET value = '2' WHERE key = 'schema_version'`);
+  }
+}
+```
+
+## In-Memory Caching
+
+```typescript
+export class UserCache extends DurableObject {
+  cache = new Map<string, User>();
+  async getUser(id: string): Promise<User> {
+    if (this.cache.has(id)) return this.cache.get(id)!;
+    const user = await this.ctx.storage.get<User>(`user:${id}`);
+    if (user) this.cache.set(id, user);
+    return user;
+  }
+  async updateUser(id: string, data: Partial<User>) {
+    const updated = { ...await this.getUser(id), ...data };
+    this.cache.set(id, updated);
+    await this.ctx.storage.put(`user:${id}`, updated);
+    return updated;
+  }
+}
+```
+
+## Rate Limiting
+
+```typescript
+export class RateLimiter extends DurableObject {
+  async checkLimit(key: string, limit: number, window: number): Promise<boolean> {
+    const now = Date.now();
+    this.sql.exec('DELETE FROM requests WHERE key = ? AND timestamp < ?', key, now - window);
+    const count = this.sql.exec('SELECT COUNT(*) as count FROM requests WHERE key = ?', key).one().count;
+    if (count >= limit) return false;
+    this.sql.exec('INSERT INTO requests (key, timestamp) VALUES (?, ?)', key, now);
+    return true;
+  }
+}
+```
+
+## Batch Processing with Alarms
+
+```typescript
+export class BatchProcessor extends DurableObject {
+  pending: string[] = [];
+  async addItem(item: string) {
+    this.pending.push(item);
+    if (!await this.ctx.storage.getAlarm()) await this.ctx.storage.setAlarm(Date.now() + 5000);
+  }
+  async alarm() {
+    const items = [...this.pending];
+    this.pending = [];
+    this.sql.exec(`INSERT INTO processed_items (item, timestamp) VALUES ${items.map(() => "(?, ?)").join(", ")}`, ...items.flatMap(item => [item, Date.now()]));
+  }
+}
+```
+
+## Initialization Pattern
+
+```typescript
+export class Counter extends DurableObject {
+  value: number;
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    ctx.blockConcurrencyWhile(async () => { this.value = (await ctx.storage.get("value")) || 0; });
+  }
+  async increment() {
+    this.value++;
+    this.ctx.storage.put("value", this.value); // Don't await (output gate protects)
+    return this.value;
+  }
+}
+```
+
+## Safe Counter / Optimized Write
+
+```typescript
+// Input gate blocks other requests
+async getUniqueNumber(): Promise<number> {
+  let val = await this.ctx.storage.get("counter");
+  await this.ctx.storage.put("counter", val + 1);
+  return val;
+}
+
+// No await on write - output gate delays response until write confirms
+async increment(): Promise<Response> {
+  let val = await this.ctx.storage.get("counter");
+  this.ctx.storage.put("counter", val + 1);
+  return new Response(String(val));
+}
+```
+
+## Cleanup
+
+```typescript
+async cleanup() {
+  await this.ctx.storage.deleteAlarm(); // Separate from deleteAll
+  await this.ctx.storage.deleteAll();
+}
+```

package/dist/template/.opencode/skill/cloudflare/references/durable-objects/README.md

@@ -0,0 +1,125 @@
+# Cloudflare Durable Objects
+
+Expert guidance for building stateful applications with Cloudflare Durable Objects.
+
+## Overview
+
+Durable Objects combine compute with storage in globally-unique, strongly-consistent packages:
+- **Globally unique instances**: Each DO has unique ID for multi-client coordination
+- **Co-located storage**: Fast, strongly-consistent storage with compute
+- **Automatic placement**: Objects spawn near first request location
+- **Stateful serverless**: In-memory state + persistent storage
+- **Single-threaded**: Serial request processing (no race conditions)
+
+## When to Use DOs
+
+Use DOs for **stateful coordination**, not stateless request handling:
+- **Coordination**: Multiple clients interacting with shared state (chat rooms, multiplayer games)
+- **Strong consistency**: Operations must serialize to avoid races (booking systems, inventory)
+- **Per-entity storage**: Each user/tenant/resource needs isolated database (multi-tenant SaaS)
+- **Persistent connections**: Long-lived WebSockets that survive across requests
+- **Per-entity scheduled work**: Each entity needs its own timer (subscription renewals, game timeouts)
+
+## When NOT to Use DOs
+
+| Scenario | Use Instead |
+|----------|-------------|
+| Stateless request handling | Workers |
+| Maximum global distribution | Workers |
+| High fan-out (independent requests) | Workers |
+| Global singleton handling all traffic | Shard across multiple DOs |
+| High-frequency pub/sub | Queues |
+| Long-running continuous processes | Workers + Alarms |
+| Chatty microservice (every request) | Reconsider architecture |
+| Eventual consistency OK, read-heavy | KV |
+| Relational queries across entities | D1 |
+
+## Design Heuristics
+
+Model each DO around your **atom of coordination**—the logical unit needing serialized access (user, room, document, session).
+
+| Characteristic | Feels Right | Question It | Reconsider |
+|----------------|-------------|-------------|------------|
+| Requests/sec (sustained) | < 100 | 100-500 | > 500 |
+| Storage keys | < 100 | 100-1000 | > 1000 |
+| Total state size | < 10MB | 10MB-100MB | > 1GB |
+| Alarm frequency | Minutes-hours | Every 30s | Every few seconds |
+| WebSocket duration | Short bursts | Hours (hibernating) | Days always-on |
+| Fan-out from this DO | Never/rarely | To < 10 DOs | To 100+ DOs |
+
+## Core Concepts
+
+### Class Structure
+All DOs extend `DurableObject` base class with constructor receiving `DurableObjectState` (storage, WebSockets, alarms) and `Env` (bindings).
+
+### Accessing from Workers
+Workers use bindings to get stubs, then call RPC methods directly (recommended) or use fetch handler (legacy).
+
+### ID Generation
+- `idFromName()`: Deterministic, named coordination
+- `newUniqueId()`: Random IDs for sharding
+- `idFromString()`: Derive from existing IDs
+- Jurisdiction option: Data locality
+
+### Storage Options
+- **SQLite** (recommended): Structured data, transactions, 10GB/DO
+- **Synchronous KV API**: Simple key-value on SQLite objects
+- **Asynchronous KV API**: Legacy/advanced use cases
+
+### Special Features
+- **Alarms**: Schedule future execution per-DO
+- **WebSocket Hibernation**: Zero-cost idle connections
+- **Point-in-Time Recovery**: Restore to any point in 30 days
+
+## Quick Start
+
+```typescript
+import { DurableObject } from "cloudflare:workers";
+
+export class Counter extends DurableObject<Env> {
+  async increment(): Promise<number> {
+    const result = this.ctx.storage.sql.exec(
+      `INSERT INTO counters (id, value) VALUES (1, 1)
+       ON CONFLICT(id) DO UPDATE SET value = value + 1
+       RETURNING value`
+    ).one();
+    return result.value;
+  }
+}
+
+// Worker access
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const id = env.COUNTER.idFromName("global");
+    const stub = env.COUNTER.get(id);
+    const count = await stub.increment();
+    return new Response(`Count: ${count}`);
+  }
+};
+```
+
+## Essential Commands
+
+```bash
+npx wrangler dev              # Local dev with DOs
+npx wrangler dev --remote     # Test against prod DOs
+npx wrangler deploy           # Deploy + auto-apply migrations
+```
+
+## Resources
+
+**Docs**: https://developers.cloudflare.com/durable-objects/  
+**API Reference**: https://developers.cloudflare.com/durable-objects/api/  
+**Examples**: https://developers.cloudflare.com/durable-objects/examples/
+
+## In This Reference
+
+- [Configuration](./configuration.md) - wrangler.jsonc setup, migrations, bindings
+- [API](./api.md) - Class structure, storage APIs, alarms, WebSockets
+- [Patterns](./patterns.md) - Rate limiting, locks, real-time collab, sessions
+- [Gotchas](./gotchas.md) - Limits, common issues, troubleshooting
+
+## See Also
+
+- [Workers](../workers/README.md) - Core Workers runtime
+- [DO Storage](../do-storage/README.md) - Deep dive on storage APIs

package/dist/template/.opencode/skill/cloudflare/references/durable-objects/api.md

@@ -0,0 +1,152 @@
+# Durable Objects API
+
+## Class Structure
+
+```typescript
+import { DurableObject } from "cloudflare:workers";
+
+export class MyDO extends DurableObject<Env> {
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    // Initialize storage/run migrations before any requests
+    ctx.blockConcurrencyWhile(async () => {
+      await this.migrate();
+    });
+  }
+  async myMethod(arg: string): Promise<string> { return arg; }
+  async alarm() { }
+  async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) { }
+}
+```
+
+## Concurrency Model
+
+### Input/Output Gates
+
+DOs are single-threaded but async/await allows request interleaving. The runtime uses **gates** to prevent data races:
+
+**Input gates** block new events while synchronous JS executes. Awaiting async ops opens the gate, allowing interleaving. Storage operations provide special protection.
+
+**Output gates** hold outgoing network messages until pending storage writes complete—clients never see confirmation of unpersisted data.
+
+### Write Coalescing
+
+Multiple storage writes without intervening `await` are automatically batched into a single atomic transaction:
+
+```typescript
+async transfer(fromId: string, toId: string, amount: number) {
+  // All three writes commit together atomically
+  this.ctx.storage.sql.exec("UPDATE accounts SET balance = balance - ? WHERE id = ?", amount, fromId);
+  this.ctx.storage.sql.exec("UPDATE accounts SET balance = balance + ? WHERE id = ?", amount, toId);
+  this.ctx.storage.sql.exec("INSERT INTO transfers (from_id, to_id, amount) VALUES (?, ?, ?)", fromId, toId, amount);
+}
+```
+
+### blockConcurrencyWhile()
+
+Guarantees no other events process until callback completes. **Use sparingly**—only for initialization/migrations.
+
+```typescript
+constructor(ctx: DurableObjectState, env: Env) {
+  super(ctx, env);
+  ctx.blockConcurrencyWhile(async () => {
+    const version = this.ctx.storage.sql.exec<{ version: number }>("PRAGMA user_version").one()?.version ?? 0;
+    if (version < 1) {
+      this.ctx.storage.sql.exec(`CREATE TABLE IF NOT EXISTS data (...); PRAGMA user_version = 1;`);
+    }
+  });
+}
+```
+
+**Anti-pattern**: Using `blockConcurrencyWhile()` on every request or across I/O (fetch, KV, R2) severely degrades throughput. For regular requests, rely on input/output gates and write coalescing.
+
+### Optimistic Locking (Non-Storage I/O)
+
+Input gates only protect during storage ops. External I/O like `fetch()` allows interleaving. Use check-and-set:
+
+```typescript
+async updateFromExternal(key: string) {
+  const version = this.ctx.storage.sql.exec<{ v: number }>("SELECT version as v FROM data WHERE key = ?", key).one()?.v;
+  const externalData = await fetch("https://api.example.com/data");  // Other requests can interleave here
+  const newVersion = this.ctx.storage.sql.exec<{ v: number }>("SELECT version as v FROM data WHERE key = ?", key).one()?.v;
+  
+  if (version !== newVersion) throw new Error("Concurrent modification");
+  this.ctx.storage.sql.exec("UPDATE data SET value = ?, version = version + 1 WHERE key = ?", await externalData.text(), key);
+}
+```
+
+## SQLite Storage
+
+```typescript
+// Query
+const cursor = this.ctx.storage.sql.exec("SELECT * FROM users WHERE age > ?", 18);
+cursor.toArray()          // All rows
+cursor.one()              // 1 row or throw
+cursor.raw().toArray()    // [[1, 'Alice']]
+cursor.rowsRead, cursor.rowsWritten, cursor.columnNames
+this.ctx.storage.sql.databaseSize
+
+// Schema
+this.ctx.storage.sql.exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)");
+```
+
+## KV Storage
+
+```typescript
+// Sync (SQLite only)
+this.ctx.storage.kv.get/put/delete("key", value)
+this.ctx.storage.kv.list({ prefix: "user:" })
+
+// Async
+await this.ctx.storage.get/put/delete("key", value)
+await this.ctx.storage.put({ k1: "a", k2: "b" })  // Batch 128 max
+await this.ctx.storage.list({ prefix: "user:", start: "user:100", limit: 50 })
+await this.ctx.storage.deleteAll()
+```
+
+## Transactions
+
+```typescript
+// Sync
+this.ctx.storage.transactionSync(() => { /* SQL ops */ });
+
+// Async
+await this.ctx.storage.transaction(async (txn) => {
+  await txn.get/put/delete("key", value);  // Throw to rollback
+});
+```
+
+## Point-in-Time Recovery
+
+```typescript
+await this.ctx.storage.getCurrentBookmark()
+await this.ctx.storage.getBookmarkForTime(Date.now() - 86400000)
+await this.ctx.storage.onNextSessionRestoreBookmark(bookmark)  // Call ctx.abort() after
+```
+
+## Alarms
+
+```typescript
+await this.ctx.storage.setAlarm(Date.now() + 3600000)
+await this.ctx.storage.getAlarm()
+await this.ctx.storage.deleteAlarm()
+async alarm() { /* runs when fires */ }
+```
+
+## WebSockets
+
+```typescript
+async fetch(req: Request): Promise<Response> {
+  const [client, server] = Object.values(new WebSocketPair());
+  this.ctx.acceptWebSocket(server, ["room:123"]);
+  server.serializeAttachment({ userId: "abc" });
+  return new Response(null, { status: 101, webSocket: client });
+}
+
+async webSocketMessage(ws: WebSocket, msg: string | ArrayBuffer) {
+  const data = ws.deserializeAttachment();
+  for (const c of this.ctx.getWebSockets()) c.send(msg);
+}
+
+// Management: getWebSockets(), getTags(ws), ws.send/close()
+```

package/dist/template/.opencode/skill/cloudflare/references/durable-objects/configuration.md

@@ -0,0 +1,148 @@
+# Durable Objects Configuration
+
+## Basic Setup
+
+```jsonc
+{
+  "name": "my-worker",
+  "main": "src/index.ts",
+  "compatibility_date": "2024-04-03",
+  "durable_objects": {
+    "bindings": [
+      { "name": "MY_DO", "class_name": "MyDO" },
+      { "name": "EXTERNAL", "class_name": "ExternalDO", "script_name": "other-worker" }
+    ]
+  },
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["MyDO"] }
+  ]
+}
+```
+
+## Migrations
+
+```jsonc
+{
+  "migrations": [
+    // Create new SQLite-backed class (recommended for new classes)
+    { "tag": "v1", "new_sqlite_classes": ["MyDO"] },
+    
+    // Create new KV-backed class (legacy, paid only)
+    // { "tag": "v1", "new_classes": ["MyDO"] },
+    
+    // Rename class - preserves all data and object IDs
+    { "tag": "v2", "renamed_classes": [{ "from": "OldName", "to": "NewName" }] },
+    
+    // Transfer between scripts - requires coordination
+    { "tag": "v3", "transferred_classes": [{ "from": "Src", "from_script": "old-worker", "to": "Dest" }] },
+    
+    // DELETE - DESTROYS ALL DATA PERMANENTLY, NO RECOVERY
+    { "tag": "v4", "deleted_classes": ["Obsolete"] }
+  ]
+}
+```
+
+**Migration rules:**
+- Tags must be unique and sequential
+- No rollback mechanism—test with `--dry-run` first
+- Auto-applied on deploy
+- `renamed_classes` preserves data and IDs
+- `deleted_classes` is irreversible—all storage gone
+- Transfers between scripts require both scripts deployed with coordinated migrations
+
+## Advanced
+
+```jsonc
+{
+  "limits": { "cpu_ms": 300000 },  // Default 30s, max 300s
+  "env": {
+    "production": {
+      "durable_objects": {
+        "bindings": [{ "name": "MY_DO", "class_name": "MyDO", "environment": "production" }]
+      }
+    }
+  }
+}
+```
+
+## Types
+
+```typescript
+import { DurableObject } from "cloudflare:workers";
+
+interface Env {
+  MY_DO: DurableObjectNamespace<MyDO>;
+}
+
+export class MyDO extends DurableObject<Env> {}
+
+type DurableObjectNamespace<T> = {
+  newUniqueId(options?: { jurisdiction?: string }): DurableObjectId;
+  idFromName(name: string): DurableObjectId;
+  idFromString(id: string): DurableObjectId;
+  get(id: DurableObjectId): DurableObjectStub<T>;
+};
+```
+
+## Testing with Vitest
+
+```typescript
+// vitest.config.ts
+import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+
+export default defineWorkersConfig({
+  test: {
+    poolOptions: {
+      workers: { wrangler: { configPath: "./wrangler.toml" } },
+    },
+  },
+});
+```
+
+```typescript
+// test/my-do.test.ts
+import { env, runInDurableObject, runDurableObjectAlarm } from "cloudflare:test";
+import { describe, it, expect } from "vitest";
+
+describe("MyDO", () => {
+  it("handles RPC methods", async () => {
+    const id = env.MY_DO.idFromName("test");
+    const stub = env.MY_DO.get(id);
+    
+    const result = await stub.myMethod("test-arg");
+    expect(result).toBe("test-arg");
+  });
+
+  it("can access storage directly", async () => {
+    const id = env.MY_DO.idFromName("test");
+    const stub = env.MY_DO.get(id);
+    
+    await runInDurableObject(stub, async (instance, state) => {
+      const count = state.storage.sql
+        .exec<{ count: number }>("SELECT COUNT(*) as count FROM data")
+        .one();
+      expect(count.count).toBe(0);
+    });
+  });
+
+  it("can trigger alarms", async () => {
+    const id = env.MY_DO.idFromName("test");
+    const stub = env.MY_DO.get(id);
+    
+    const alarmRan = await runDurableObjectAlarm(stub);
+    expect(alarmRan).toBe(false); // No alarm scheduled
+  });
+});
+```
+
+## Commands
+
+```bash
+npx wrangler dev                                       # Local dev
+npx wrangler dev --remote                              # Test prod DOs
+npx wrangler deploy                                    # Deploy + migrations
+npx wrangler deploy --dry-run                          # Validate only
+npx wrangler durable-objects list                      # List namespaces
+npx wrangler durable-objects info <namespace> <id>     # Object info
+npx wrangler durable-objects delete <namespace> <id>   # Delete object
+```

package/dist/template/.opencode/skill/cloudflare/references/durable-objects/gotchas.md

@@ -0,0 +1,158 @@
+# Durable Objects Gotchas
+
+## Limits
+
+| Resource | Free | Paid |
+|----------|------|------|
+| Storage per DO | 10GB (SQLite) | 10GB (SQLite) |
+| Total storage | 5GB | Unlimited |
+| DO classes | 100 | 500 |
+| Requests/sec/DO | ~1000 | ~1000 |
+| CPU time | 30s default, 300s max | 30s default, 300s max |
+| WebSocket message | 32MiB | 32MiB |
+| SQL columns | 100 | 100 |
+| SQL statement | 100KB | 100KB |
+| Key+value size | 2MB | 2MB |
+
+## Billing Gotchas
+
+### Duration Billing Trap
+DOs bill for **wall-clock time** while active, not CPU time. WebSocket open 8 hours = 8 hours duration billing, even if DO processed 50 small messages.
+
+**Fix**: Use Hibernatable WebSockets API. DO sleeps while maintaining connections, only wakes (and bills) when messages arrive.
+
+### storage.list() on Every Request
+Storage reads are cheap but not free. Calling `storage.list()` or multiple `storage.get()` on every request adds up.
+
+**Fix**: Profile actual usage. Options:
+- `storage.get(['key1', 'key2', 'key3'])` - cheapest if only need specific keys
+- `storage.list()` once on wake, cache in memory - cheapest if serving many requests per wake cycle
+- Single `storage.get('allData')` with combined object - cheapest if often need multiple keys together
+
+### Alarm Recursion
+Scheduling `setAlarm()` every 5 minutes = 288 wake-ups/day × minimum billable duration. Across thousands of DOs, you're waking them all whether work exists or not.
+
+**Fix**: Only schedule alarms when actual work is pending. Check if alarm is needed before setting.
+
+### WebSocket Never Closes
+If users close browser tabs without proper disconnect and you don't handle it, connection stays "open" from DO's perspective, preventing hibernation.
+
+**Fix**:
+1. Handle `webSocketClose` and `webSocketError` events
+2. Implement heartbeat/ping-pong to detect dead connections
+3. Use Hibernatable WebSockets API properly
+
+### Singleton vs Sharding
+Global singleton DO handling all traffic = bottleneck + continuous duration billing (never hibernates).
+
+| Design | Cost Pattern |
+|--------|--------------|
+| One global DO | Never hibernates, continuous billing |
+| Per-user DO | Each only wakes for their requests, most hibernate |
+| Per-user-per-hour | Many cold starts, many minimum durations |
+
+**Fix**: Use per-entity DOs (per-user, per-room, per-document). They hibernate between activity.
+
+### Batching Reads
+Five separate `storage.get()` calls > one `storage.get(['k1','k2','k3','k4','k5'])`. Each operation has overhead.
+
+**Fix**: Batch reads/writes. Writes without intervening `await` are automatically coalesced into single atomic transaction.
+
+### Hibernation State Loss
+In-memory state is **lost** when DO hibernates or evicts. Waking DO reconstructs from storage.
+
+**Fix**:
+1. Store all important state in SQLite storage
+2. Use `blockConcurrencyWhile()` in constructor to load state on wake
+3. Cache in memory for current wake cycle only
+4. Accept every wake is potentially "cold"
+
+### Fan-Out Tax
+Event notifying 1,000 DOs = 1,000 DO invocations billed immediately. Queue pattern doesn't reduce invocations but provides retries and batching.
+
+**Fix**: For time-sensitive, accept cost. For deferrable, use Queues for retry/dead-letter handling.
+
+### Idempotency Key Explosion
+Creating one DO per idempotency key (used once) = millions of single-use DOs that persist until deleted.
+
+**Fix**:
+1. Hash idempotency keys into N sharded buckets
+2. Store records as rows in single DO's SQLite table
+3. Implement TTL cleanup via alarms
+4. Consider if KV is sufficient (if strong consistency not needed)
+
+### Storage Compaction
+Individual writes billed per-operation. Writing 100 events individually = 100× the write operations vs batching.
+
+**Fix**: Batch writes. Multiple `INSERT` statements without intervening `await` coalesce into single transaction.
+
+### waitUntil() Behavior
+`ctx.waitUntil()` keeps DO alive (billed) until promises resolve. Waiting for slow external calls = paying for wait time.
+
+**Fix**: For true background work, use alarms or Queues instead of `waitUntil()`.
+
+### KV vs DO Storage
+For read-heavy, write-rare, eventually-consistent-OK data: **KV is cheaper**.
+
+| | KV | DO Storage |
+|-|----|----|
+| Reads | Global edge cache, cheap | Every read hits DO compute |
+| Writes | ~60s propagation | Immediate consistency |
+| Use case | Config, sessions, cache | Read-modify-write, coordination |
+
+## Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| DO overloaded (503) | Single DO bottleneck | Shard across DOs with random/deterministic IDs |
+| Storage quota exceeded | Write failures | Upgrade plan or cleanup via alarms |
+| CPU exceeded | Terminated mid-request | Increase `limits.cpu_ms` or chunk work |
+| WebSockets disconnect | Eviction | Use hibernation + reconnection logic |
+| Migration failed | Deploy error | Check tag uniqueness, class names, use `--dry-run` |
+| RPC not found | Old compatibility_date | Update to >= 2024-04-03 or use fetch |
+| One alarm limit | Need multiple timers | Use event queue pattern (store events, single alarm) |
+| Constructor expensive | Slow cold starts | Lazy load in methods, cache after first load |
+
+## RPC vs Fetch
+
+| | RPC | Fetch |
+|-|-----|-------|
+| Type safety | Full TypeScript support | Manual parsing |
+| Simplicity | Direct method calls | HTTP request/response |
+| Performance | Slightly faster | HTTP overhead |
+| Requirement | compatibility_date >= 2024-04-03 | Always works |
+| Use case | **Default choice** | Legacy, proxying |
+
+```typescript
+// RPC (recommended)
+const result = await stub.myMethod(arg);
+
+// Fetch (legacy)
+const response = await stub.fetch(new Request("http://do/endpoint"));
+```
+
+## Migration Gotchas
+
+- Tags must be unique and sequential
+- No rollback mechanism
+- `deleted_classes` **destroys ALL data** permanently
+- Test with `--dry-run` before production deploy
+- Transfers between scripts need coordination
+- Renames preserve data and IDs
+
+## Debugging
+
+```bash
+npx wrangler dev              # Local development
+npx wrangler dev --remote     # Test against production DOs
+npx wrangler tail             # Stream logs
+npx wrangler durable-objects list
+npx wrangler durable-objects info <namespace> <id>
+```
+
+```typescript
+// Storage diagnostics
+this.ctx.storage.sql.databaseSize  // Current storage usage
+cursor.rowsRead                    // Rows scanned
+cursor.rowsWritten                 // Rows modified
+```