feat(pds): implement firehose WebSocket event stream (#4)

* feat(pds): implement firehose WebSocket event stream

Implements Phase 4 of the Edge PDS plan - the firehose event stream that enables federation with the Bluesky network.

**Core Implementation:**
- Sequencer class for commit event log management
- WebSocket hibernation API handlers in AccountDO
- DAG-CBOR frame encoding (header + body)
- Event broadcasting to connected clients
- Cursor-based backfill and validation
- SQLite firehose_events table for event persistence

**XRPC Endpoints:**
- GET /xrpc/com.atproto.sync.subscribeRepos?cursor={seq}

**Testing:**
- 6 new firehose tests (event sequencing, cursor validation, backfill)
- 42 additional tests covering authentication, concurrency, error handling
- All 48 tests passing

**Database Schema:**
- firehose_events table with autoincrement seq, event_type, payload, created_at
- Integrated into existing SqliteRepoStorage initialization

The relay can now subscribe to this PDS and sync commits in real-time.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* docs: update CLAUDE.md and EDGE_PDS_PLAN.md to reflect Phase 4 completion

- Updated test count from 28 to 48 tests (16 storage + 26 XRPC + 6 firehose)
- Added firehose implementation notes to CLAUDE.md
- Marked Phase 4 as completed in EDGE_PDS_PLAN.md
- Updated XRPC endpoints list to include subscribeRepos
- Documented firehose architecture and event flow

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

* fix(pds): resolve CORS and WebSocket serialization issues

- Add CORS middleware using Hono's cors helper for all XRPC endpoints
- Fix WebSocket serialization error by using stub.fetch() instead of RPC
- Add fetch() handler to AccountDurableObject for WebSocket upgrades
- Fix CBOR frame decoding using @atproto/lex-cbor decodeAll()
- Add test scripts (test-firehose.js, create-post.js, load-env.js)
- Add TESTING.md with comprehensive testing documentation
- Update CLAUDE.md and EDGE_PDS_PLAN.md with implementation notes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: ascorbic

CLAUDE.md

@@ -1,10 +1,26 @@
 This file provides guidance to agentic coding tools when working with code in this repository.
 
+## CRITICAL: Working Directory and Plan Document
+
+**ALWAYS verify your current working directory before operating on files:**
+
+- Repository root is `atproto-worker` not `packages/pds/`
+- Use `pwd` or check `process.cwd()` to confirm location
+- Many project files (CLAUDE.md, EDGE_PDS_PLAN.md) are at repository root
+- Package-specific files are in `packages/pds/`
+
+**ALWAYS read and update the implementation plan:**
+
+- **Read** `EDGE_PDS_PLAN.md` at the repository root before starting work to understand project status
+- **Update** `EDGE_PDS_PLAN.md` when you complete phases or discover important implementation details
+- The plan tracks what's completed, what's pending, and critical technical notes
+- Keep the "Completed" section updated with new learnings (WebSocket patterns, CBOR encoding, etc.)
+
 ## Repository Structure
 
 This is a monorepo using pnpm workspaces with the following structure:
 
-- **Root**: Workspace configuration and shared tooling
+- **Root** (`atproto-worker`): Workspace configuration, shared tooling, plan documents
 - **packages/pds**: The main PDS library (`@ascorbic/pds-worker`)
 - **demos/pds**: Demo PDS deployment
 
@@ -64,16 +80,11 @@ The PDS package uses **vitest 4** with `@cloudflare/vitest-pool-workers` PR buil
 
 ### TypeScript Module Resolution
 
-The PDS package requires special handling for certain dependencies:
+The PDS package TypeScript configuration:
 
 1. **Module Resolution**: Uses `moduleResolution: "bundler"` in tsconfig.json
-2. **Custom Type Declarations**: `src/types/modules.d.ts` provides declarations for packages with broken exports:
-   - `multiformats/cid`
-   - `@ipld/dag-cbor`
-   - `uint8arrays`
-   - `multiformats/hashes/sha2`
-3. **Test Types**: `test/tsconfig.json` includes `@cloudflare/vitest-pool-workers/types` for cloudflare:test module
-4. **Import Style**: Use named imports (not namespace imports) for `verbatimModuleSyntax` compatibility
+2. **Test Types**: `test/tsconfig.json` includes `@cloudflare/vitest-pool-workers/types` for cloudflare:test module
+3. **Import Style**: Use named imports (not namespace imports) for `verbatimModuleSyntax` compatibility
 
 ### Durable Objects Architecture
 
@@ -86,16 +97,64 @@ The PDS package requires special handling for certain dependencies:
 
 ### Environment Variables
 
-Required environment variables (validated at startup):
-- `DID` - The account's DID (did:web:...)
-- `HANDLE` - The account's handle
+Required environment variables (validated at module load using `cloudflare:workers` env import):
+
+- `DID` - The account's DID (did:web:...) - validated with `ensureValidDid()`
+- `HANDLE` - The account's handle - validated with `ensureValidHandle()`
 - `PDS_HOSTNAME` - Public hostname
 - `AUTH_TOKEN` - Bearer token for write operations
 - `SIGNING_KEY` - Private key for signing commits
 - `SIGNING_KEY_PUBLIC` - Public key multibase for DID document
 
+**Note**: Environment validation happens at module scope. Worker fails fast at startup if any required variables are missing or invalid.
+
+### Protocol Helpers and Dependencies
+
+The codebase uses official @atproto packages for all protocol operations:
+
+**Encoding and Data Structures:**
+
+- `@atproto/lex-cbor` - CBOR encoding/decoding with `encode()` and `cidForCbor()`
+- `@atproto/lex-data` - CID operations via stable interface wrapping multiformats
+- `@atproto/repo` - Repository operations, `BlockMap`, `blocksToCarFile()`
+
+**Protocol Utilities:**
+
+- `@atproto/common-web` - `TID.nextStr()` for record key generation
+- `@atproto/syntax` - `AtUri.make()`, `ensureValidDid()`, `ensureValidHandle()`
+- `@atproto/crypto` - `Secp256k1Keypair` for signing operations
+- `@atproto/lexicon` - Schema validation and type definitions
+
+**Important Notes:**
+
+- Never manually construct AT URIs - use `AtUri.make(did, collection, rkey).toString()`
+- Never manually generate record keys - use `TID.nextStr()`
+- Always validate DIDs and handles using `ensureValidDid()` / `ensureValidHandle()`
+- Use `@atproto/lex-cbor` for test fixtures instead of direct `@ipld/dag-cbor`
+- CAR file export uses `blocksToCarFile()` from `@atproto/repo`
+
 ### Vitest Configuration Notes
 
 - **Module Shimming**: Uses `resolve: { conditions: ["node", "require"] }` to force CJS builds for multiformats
-- **CID Deprecation**: Ignore `'CID' is deprecated` warnings - false positive from multiformats types
 - **BlockMap/CidSet**: Access internal Map/Set via `(blocks as unknown as { map: Map<...> }).map` when iterating
+- **Test Count**: 48 tests (16 storage tests, 26 XRPC tests, 6 firehose tests)
+
+### Firehose Implementation
+
+The PDS implements the WebSocket-based firehose for real-time federation:
+
+- **Sequencer**: Manages commit event log in `firehose_events` SQLite table
+- **WebSocket Hibernation API**: DurableObject WebSocket handlers (message, close, error)
+- **Frame Encoding**: DAG-CBOR frame encoding (header + body concatenation)
+- **Event Broadcasting**: Automatic sequencing and broadcast on write operations
+- **Cursor-based Backfill**: Replay events from sequence number with validation
+
+**Event Flow:**
+
+1. `createRecord`/`deleteRecord` → sequence commit to SQLite
+2. Broadcast CBOR-encoded frame to all connected WebSocket clients
+3. Update client cursor positions in WebSocket attachments
+
+**Endpoint:**
+
+- `GET /xrpc/com.atproto.sync.subscribeRepos?cursor={seq}` - WebSocket upgrade for commit stream