@alteran/astro 0.3.8 → 0.5.2

package/src/worker/sequencer.ts

@@ -1,65 +1,41 @@
-// Types via tsconfig
-
 import type { DurableObjectState, D1Database } from '@cloudflare/workers-types';
 import { drizzle } from 'drizzle-orm/d1';
 import { commit_log } from '../db/schema';
 import { gt, eq, desc } from 'drizzle-orm';
-import {
-  createInfoFrame,
-  createCommitFrame,
-  createIdentityFrame,
-  createAccountFrame,
-  createErrorFrame,
-  type CommitMessage,
-  type RepoOp,
-} from '../lib/firehose/frames';
-import { checkCursor } from '../lib/firehose/validation';
-import { CID } from 'multiformats/cid';
-import { encodeBlocksForCommit } from '../services/car';
+import { encodeInfoFrame, encodeCommitFrame } from '../lib/firehose/frames';
 import type { Env } from '../env';
+import { fromWireStatus } from '../lib/account-state';
+import type {
+  AccountEvent,
+  Client,
+  CommitEvent,
+  IdentityEvent,
+} from './sequencer/types';
+import { reviveOps, base64ToBytes } from './sequencer/cid-helpers';
+import { createCommitPayload } from './sequencer/payload';
+import {
+  handleUpgrade,
+  type HibernatableSocket,
+  type HibernatableState,
+  type WebSocketAttachment,
+} from './sequencer/upgrade';
+import {
+  broadcastAccount,
+  broadcastCommit,
+  broadcastIdentity,
+} from './sequencer/broadcast';
+
+export type {
+  AccountEvent,
+  Client,
+  CommitEvent,
+  IdentityEvent,
+  SequencerEvent,
+} from './sequencer/types';
 
-interface Client {
-  webSocket: WebSocket;
-  id: string;
-  cursor: number;
-}
-
-interface CommitEvent {
-  seq: number;
-  did: string;
-  commitCid: string;
-  rev: string;
-  data: string; // JSON-encoded commit data
-  sig: string; // base64 signature
-  ts: number;
-  ops?: RepoOp[];
-  blocks?: Uint8Array;
-}
-
-interface IdentityEvent {
-  seq: number;
-  did: string;
-  handle?: string;
-  ts: number;
-}
-
-interface AccountEvent {
-  seq: number;
-  did: string;
-  active: boolean;
-  status?: string;
-  ts: number;
-}
-
-type SequencerEvent = CommitEvent | IdentityEvent | AccountEvent;
-
-/**
- * Sequencer Durable Object
- * Manages the firehose event stream for repository updates
- */
 export class Sequencer {
-  private readonly state: DurableObjectState;
-  private readonly env: Env & { PDS_SEQ_WINDOW?: string };
+  private readonly state: HibernatableState;
+  private readonly env: Env;
   private readonly clients = new Map<string, Client>();
   private buffer: CommitEvent[] = [];
   private readonly db: D1Database;
@@ -67,17 +43,39 @@ export class Sequencer {
   private nextSeq = 1;
   private droppedFrameCount = 0;
 
-  constructor(state: DurableObjectState, env: Env & { PDS_SEQ_WINDOW?: string }) {
-    this.state = state;
+  constructor(state: DurableObjectState, env: Env) {
+    this.state = state as HibernatableState;
     this.env = env;
     this.db = env.DB;
     this.maxWindow = parseInt(env.PDS_SEQ_WINDOW || '512', 10);
 
-    // Initialize from storage
+    // Reconcile nextSeq with DB on construction so replay and append agree
+    // after worker restarts or DO migrations.
     this.state.blockConcurrencyWhile(async () => {
-      const stored = await this.state.storage.get<number>('nextSeq');
-      if (stored) {
-        this.nextSeq = stored;
+      let base = 0;
+      try {
+        base = (await this.state.storage.get<number>('nextSeq')) || 0;
+      } catch (storageError) {
+        console.warn('Sequencer: storage.get(nextSeq) failed:', storageError);
+      }
+      try {
+        const db = drizzle(this.db);
+        const last = await db
+          .select({ seq: commit_log.seq })
+          .from(commit_log)
+          .orderBy(desc(commit_log.seq))
+          .limit(1)
+          .get();
+        const dbNext = last?.seq ? Number(last.seq) + 1 : 1;
+        if (!base || dbNext > base) base = dbNext;
+      } catch (dbError) {
+        console.warn('Sequencer: commit_log max(seq) failed:', dbError);
+      }
+      this.nextSeq = base > 0 ? base : 1;
+      try {
+        await this.state.storage.put('nextSeq', this.nextSeq);
+      } catch (storageError) {
+        console.warn('Sequencer: storage.put(nextSeq) failed:', storageError);
       }
     });
   }
@@ -85,18 +83,16 @@ export class Sequencer {
   async fetch(request: Request): Promise<Response> {
     const url = new URL(request.url);
 
-    // Handle event notifications from PDS
     if (request.method === 'POST') {
-      if (url.pathname === '/commit') {
-        return this.handleCommitNotification(request);
-      } else if (url.pathname === '/identity') {
-        return this.handleIdentityNotification(request);
-      } else if (url.pathname === '/account') {
-        return this.handleAccountNotification(request);
-      }
+      if (url.pathname === '/commit') return this.handleCommitNotification(request);
+      if (url.pathname === '/identity') return this.handleIdentityNotification(request);
+      if (url.pathname === '/account') return this.handleAccountNotification(request);
+    }
+
+    if (request.method === 'GET' && url.pathname === '/metrics') {
+      return this.handleMetrics();
     }
 
-    // Handle WebSocket upgrade for firehose subscription
     const upgradeHeader = request.headers.get('Upgrade');
     if (upgradeHeader !== 'websocket') {
       return new Response('Expected websocket', { status: 426 });
@@ -105,9 +101,6 @@ export class Sequencer {
     return this.handleWebSocketUpgrade(request, url);
   }
 
-  /**
-   * Handle commit notification from PDS
-   */
   private async handleCommitNotification(request: Request): Promise<Response> {
     try {
       const body = (await request.json()) as {
@@ -116,50 +109,79 @@ export class Sequencer {
         rev: string;
         data: string;
         sig: string;
-        ops?: RepoOp[];
-        blocks?: string; // base64-encoded CAR
+        ops?: unknown;
+        blocks?: string;
       };
 
-      // Helper: base64 to Uint8Array (workers-safe)
-      const b64ToBytes = (b64: string): Uint8Array => {
-        const bin = atob(b64);
-        const out = new Uint8Array(bin.length);
-        for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
-        return out;
-      };
+      const ops = reviveOps(body.ops);
+
+      const db = drizzle(this.db);
+      let seqForEvent: number | null = null;
+      let tsForEvent = Date.now();
+      try {
+        const row = await db
+          .select({
+            seq: commit_log.seq,
+            rev: commit_log.rev,
+            data: commit_log.data,
+            sig: commit_log.sig,
+            ts: commit_log.ts,
+          })
+          .from(commit_log)
+          .where(eq(commit_log.cid, body.commitCid))
+          .limit(1)
+          .get();
+        if (row && typeof row.seq === 'number') {
+          seqForEvent = row.seq;
+          body.rev = row.rev;
+          body.data = row.data;
+          body.sig = row.sig;
+          tsForEvent = row.ts ?? tsForEvent;
+        }
+      } catch (lookupError) {
+        console.warn('commit_log lookup failed:', lookupError);
+      }
+
+      if (seqForEvent == null) {
+        seqForEvent = this.nextSeq++;
+        await this.state.storage.put('nextSeq', this.nextSeq);
+        try {
+          await db
+            .insert(commit_log)
+            .values({
+              seq: seqForEvent,
+              cid: body.commitCid,
+              rev: body.rev,
+              data: body.data,
+              sig: body.sig,
+              ts: tsForEvent,
+            })
+            .run();
+        } catch (insertError) {
+          console.warn('commit_log insert failed:', insertError);
+        }
+      } else if (seqForEvent >= this.nextSeq) {
+        this.nextSeq = seqForEvent + 1;
+        try {
+          await this.state.storage.put('nextSeq', this.nextSeq);
+        } catch (putError) {
+          console.warn('Sequencer: storage.put(nextSeq) failed:', putError);
+        }
+      }
 
       const event: CommitEvent = {
-        seq: this.nextSeq++,
+        seq: seqForEvent,
         did: body.did,
         commitCid: body.commitCid,
         rev: body.rev,
         data: body.data,
         sig: body.sig,
-        ts: Date.now(),
-        ops: body.ops,
-        blocks: body.blocks ? b64ToBytes(body.blocks) : undefined,
+        ts: tsForEvent,
+        ops,
+        blocks: body.blocks ? base64ToBytes(body.blocks) : undefined,
       };
 
-      // Persist sequence number
-      await this.state.storage.put('nextSeq', this.nextSeq);
-
-      // Update commit_log with assigned sequence for this commit (if row exists)
-      try {
-        const db = drizzle(this.db);
-        const res = await db.update(commit_log).set({ seq: event.seq }).where(eq(commit_log.cid, event.commitCid)).run();
-        // If the row didn't exist (unexpected), insert a minimal row so replay works
-        // Note: drizzle's run() returns a driver-specific result; we just best-effort insert
-        if ((res as any)?.success === false) {
-          await db.insert(commit_log).values({ seq: event.seq, cid: event.commitCid, rev: event.rev, data: event.data, sig: event.sig, ts: event.ts }).run();
-        }
-      } catch (e) {
-        console.warn('commit_log seq update failed:', e);
-      }
-
-      // Add to buffer
       this.appendCommit(event);
-
-      // Broadcast to all connected clients
       await this.broadcastCommit(event);
 
       return new Response('ok');
@@ -169,29 +191,21 @@ export class Sequencer {
     }
   }
 
-  /**
-   * Handle identity notification from PDS (handle changes)
-   */
   private async handleIdentityNotification(request: Request): Promise<Response> {
     try {
-      const body = (await request.json()) as {
-        did: string;
-        handle?: string;
-      };
-
+      const body = (await request.json()) as { did: string; handle?: string };
       const event: IdentityEvent = {
         seq: this.nextSeq++,
         did: body.did,
         handle: body.handle,
         ts: Date.now(),
       };
-
-      // Persist sequence number
-      await this.state.storage.put('nextSeq', this.nextSeq);
-
-      // Broadcast to all connected clients
+      try {
+        await this.state.storage.put('nextSeq', this.nextSeq);
+      } catch (putError) {
+        console.warn('Sequencer: storage.put(nextSeq) failed:', putError);
+      }
       await this.broadcastIdentity(event);
-
       return new Response('ok');
     } catch (error) {
       console.error('Failed to handle identity notification:', error);
@@ -199,31 +213,21 @@ export class Sequencer {
     }
   }
 
-  /**
-   * Handle account notification from PDS (account status changes)
-   */
   private async handleAccountNotification(request: Request): Promise<Response> {
     try {
-      const body = (await request.json()) as {
-        did: string;
-        active: boolean;
-        status?: string;
-      };
-
+      const body = (await request.json()) as { did: string; active: boolean; status?: string };
       const event: AccountEvent = {
         seq: this.nextSeq++,
         did: body.did,
-        active: body.active,
-        status: body.status,
+        state: fromWireStatus({ active: body.active, status: body.status }),
         ts: Date.now(),
       };
-
-      // Persist sequence number
-      await this.state.storage.put('nextSeq', this.nextSeq);
-
-      // Broadcast to all connected clients
+      try {
+        await this.state.storage.put('nextSeq', this.nextSeq);
+      } catch (putError) {
+        console.warn('Sequencer: storage.put(nextSeq) failed:', putError);
+      }
       await this.broadcastAccount(event);
-
       return new Response('ok');
     } catch (error) {
       console.error('Failed to handle account notification:', error);
@@ -231,321 +235,110 @@ export class Sequencer {
     }
   }
 
-  /**
-   * Handle WebSocket upgrade for firehose subscription
-   */
-  private async handleWebSocketUpgrade(request: Request, url: URL): Promise<Response> {
-    const pair = new WebSocketPair();
-    const [client, server] = Object.values(pair);
-    const id = crypto.randomUUID();
-    const ws = server as unknown as WebSocket;
-
-    ws.accept();
-
-    // Parse cursor parameter
-    const cursorParam = url.searchParams.get('cursor');
-    const cursor = cursorParam ? parseInt(cursorParam, 10) : 0;
-
-    // Validate cursor
-    if (cursor > this.nextSeq - 1) {
-      // Future cursor error
-      const err = checkCursor(cursor, this.nextSeq - 1) ?? createErrorFrame('FutureCursor', 'Cursor is ahead of current sequence').toFramedBytes();
-      ws.send(err);
-      ws.close(1008, 'FutureCursor');
-      return new Response(null, { status: 101, webSocket: client });
-    }
-
-    const clientObj: Client = { webSocket: ws, id, cursor };
-    this.clients.set(id, clientObj);
-
-    // Send #info frame on connection
-    const infoFrame = createInfoFrame('com.atproto.sync.subscribeRepos', 'Connected to PDS firehose');
-    try {
-      ws.send(infoFrame.toFramedBytes());
-    } catch (error) {
-      console.error('Failed to send info frame:', error);
-    }
-
-    // Keep the connection alive to avoid intermediary idle timeouts (e.g., CF edge)
-    // Send a lightweight #info heartbeat every ~25s. Most clients ignore unknown #info
-    // messages; this is safe and keeps the socket active.
-    const keepalive = setInterval(() => {
-      try {
-        const ka = createInfoFrame('keepalive', 'ping');
-        ws.send(ka.toFramedBytes());
-      } catch {}
-    }, 25_000);
-
-    // Set up event handlers
-    ws.addEventListener('message', (evt) => {
-      try {
-        const data = typeof evt.data === 'string' ? evt.data : '';
-        if (data === 'ping') {
-          ws.send('pong');
-        }
-      } catch (error) {
-        console.error('WebSocket message error:', error);
-      }
-    });
-
-    ws.addEventListener('close', () => {
-      this.clients.delete(id);
-      clearInterval(keepalive);
-    });
-
-    ws.addEventListener('error', () => {
-      this.clients.delete(id);
-      clearInterval(keepalive);
+  private handleWebSocketUpgrade(request: Request, url: URL): Response {
+    const hibernate = String(this.env.PDS_WS_HIBERNATE ?? 'true').toLowerCase() !== 'false';
+    return handleUpgrade(request, url, {
+      state: this.state,
+      nextSeq: this.nextSeq,
+      hibernate,
+      onClient: (id, cursor, server) => {
+        this.clients.set(id, { webSocket: server, id, cursor });
+      },
     });
-
-    // Replay buffered events if cursor provided
-    if (cursor > 0) {
-      await this.replayFromCursor(ws, cursor);
-    }
-
-    return new Response(null, { status: 101, webSocket: client });
   }
 
-  /**
-   * Replay events from cursor
-   */
   private async replayFromCursor(ws: WebSocket, cursor: number): Promise<void> {
-    // First try from buffer
     const bufferedEvents = this.buffer.filter((e) => e.seq > cursor);
 
     if (bufferedEvents.length > 0) {
       for (const event of bufferedEvents) {
         try {
-          const frame = await this.createCommitFrame(event);
-          ws.send(frame.toFramedBytes());
+          const message = await createCommitPayload(this.env, this.db, event);
+          ws.send(encodeCommitFrame(message));
         } catch (error) {
           console.error('Failed to send buffered event:', error);
         }
       }
-    } else {
-      // Fetch from database if not in buffer
-      try {
-        const db = drizzle(this.db);
-        const events = await db
-          .select()
-          .from(commit_log)
-          .where(gt(commit_log.seq, cursor))
-          .orderBy(commit_log.seq)
-          .limit(100)
-          .all();
-
-        for (const event of events) {
-          try {
-            const commitEvent: CommitEvent = {
-              seq: event.seq!,
-              did: JSON.parse(event.data).did,
-              commitCid: event.cid,
-              rev: event.rev,
-              data: event.data,
-              sig: event.sig,
-              ts: event.ts,
-            };
-            const frame = await this.createCommitFrame(commitEvent);
-            ws.send(frame.toFramedBytes());
-          } catch (error) {
-            console.error('Failed to send database event:', error);
-          }
-        }
-      } catch (error) {
-        console.error('Failed to fetch events from database:', error);
-      }
+      return;
     }
-  }
-
-  /**
-   * Broadcast commit event to all connected clients
-   */
-  private async broadcastCommit(event: CommitEvent): Promise<void> {
-    const frame = await this.createCommitFrame(event);
-    const bytes = frame.toFramedBytes();
 
-    const disconnected: string[] = [];
-
-    for (const [id, client] of Array.from(this.clients.entries())) {
-      try {
-        // Check if client's cursor is caught up
-        if (event.seq > client.cursor) {
-          client.webSocket.send(bytes);
-          client.cursor = event.seq;
+    try {
+      const db = drizzle(this.db);
+      const events = await db
+        .select()
+        .from(commit_log)
+        .where(gt(commit_log.seq, cursor))
+        .orderBy(commit_log.seq)
+        .limit(100)
+        .all();
+
+      for (const event of events) {
+        try {
+          if (event.seq == null) continue;
+          const commitEvent: CommitEvent = {
+            seq: event.seq,
+            did: JSON.parse(event.data).did,
+            commitCid: event.cid,
+            rev: event.rev,
+            data: event.data,
+            sig: event.sig,
+            ts: event.ts,
+          };
+          const message = await createCommitPayload(this.env, this.db, commitEvent);
+          ws.send(encodeCommitFrame(message));
+        } catch (error) {
+          console.error('Failed to send database event:', error);
         }
-      } catch (error) {
-        console.error(`Failed to send to client ${id}:`, error);
-        disconnected.push(id);
       }
-    }
-
-    // Clean up disconnected clients
-    for (const id of disconnected) {
-      this.clients.delete(id);
+    } catch (error) {
+      console.error('Failed to fetch events from database:', error);
     }
   }
 
-  /**
-   * Broadcast identity event to all connected clients
-   */
-  private async broadcastIdentity(event: IdentityEvent): Promise<void> {
-    const frame = createIdentityFrame({
-      seq: event.seq,
-      did: event.did,
-      time: new Date(event.ts).toISOString(),
-      handle: event.handle,
-    });
-    const bytes = frame.toFramedBytes();
-
-    const disconnected: string[] = [];
-
-    for (const [id, client] of Array.from(this.clients.entries())) {
-      try {
-        if (event.seq > client.cursor) {
-          client.webSocket.send(bytes);
-          client.cursor = event.seq;
-        }
-      } catch (error) {
-        console.error(`Failed to send to client ${id}:`, error);
-        disconnected.push(id);
-      }
-    }
-
-    for (const id of disconnected) {
-      this.clients.delete(id);
+  private getSocketTargets(): WebSocket[] {
+    let sockets: WebSocket[] = [];
+    try {
+      // workers-types WebSocket misses a few DOM-types members; the values
+      // are wire-compatible at runtime, so widen through unknown.
+      sockets = (this.state.getWebSockets?.() || []) as unknown as WebSocket[];
+    } catch (error) {
+      console.warn('Sequencer: getWebSockets failed:', error);
     }
+    return sockets.length > 0
+      ? sockets
+      : Array.from(this.clients.values()).map((c) => c.webSocket);
   }
 
-  /**
-   * Broadcast account event to all connected clients
-   */
-  private async broadcastAccount(event: AccountEvent): Promise<void> {
-    const accountFrame = createAccountFrame({
-      seq: event.seq,
-      did: event.did,
-      time: new Date(event.ts).toISOString(),
-      active: event.active,
-      status: event.status,
-    });
-    // Emit compatibility #sync frame as well
-    const { createSyncFrame } = await import('../lib/firehose/frames');
-    const syncLike = createSyncFrame({
-      seq: event.seq,
-      did: event.did,
-      time: new Date(event.ts).toISOString(),
-      active: event.active,
-      status: event.status,
-    });
-    const bytesAccount = accountFrame.toFramedBytes();
-    const bytesSync = syncLike.toFramedBytes();
-
-    const disconnected: string[] = [];
-
-    for (const [id, client] of Array.from(this.clients.entries())) {
-      try {
-        if (event.seq > client.cursor) {
-          client.webSocket.send(bytesAccount);
-          client.webSocket.send(bytesSync);
-          client.cursor = event.seq;
-        }
-      } catch (error) {
-        console.error(`Failed to send to client ${id}:`, error);
-        disconnected.push(id);
-      }
-    }
-
-    for (const id of disconnected) {
-      this.clients.delete(id);
-    }
+  private broadcastCommit(event: CommitEvent): Promise<void> {
+    return broadcastCommit(this.env, this.db, this.getSocketTargets(), event);
   }
 
-  /**
-   * Create a #commit frame from event
-   */
-  private async createCommitFrame(event: CommitEvent): Promise<ReturnType<typeof createCommitFrame>> {
-    const commitData = JSON.parse(event.data);
-
-    // If blocks weren't provided, encode them now
-    let blocks = event.blocks;
-    if (!blocks && event.ops && event.ops.length > 0) {
-      try {
-        const commitCid = CID.parse(event.commitCid);
-        // Extract MST root from commit data
-        const mstRoot = commitData.data ? CID.parse(commitData.data) : commitCid;
-        blocks = await encodeBlocksForCommit(
-          this.env as Env,
-          commitCid,
-          mstRoot,
-          event.ops,
-        );
-      } catch (error) {
-        console.error('Failed to encode blocks for commit:', error);
-        blocks = new Uint8Array();
-      }
-    }
-
-    // Resolve prev commit and since (previous rev) when available
-    let prevCid: CID | null = null;
-    try {
-      if (commitData.prev) prevCid = CID.parse(String(commitData.prev));
-    } catch {}
-
-    let since: string | null = null;
-    try {
-      const db = drizzle(this.db);
-      if (prevCid) {
-        const prev = await db.select().from(commit_log).where(eq(commit_log.cid, prevCid.toString())).get();
-        since = prev?.rev ?? null;
-      } else {
-        const row = await db.select().from(commit_log).where(gt(commit_log.seq, 0 as any)).orderBy(desc(commit_log.seq)).limit(1).get();
-        since = row?.rev ?? null;
-      }
-    } catch {}
-
-    const message: CommitMessage = {
-      seq: event.seq,
-      rebase: false,
-      tooBig: false,
-      repo: event.did,
-      commit: CID.parse(event.commitCid),
-      prev: prevCid,
-      rev: event.rev,
-      since,
-      blocks: blocks || new Uint8Array(),
-      ops: event.ops || [],
-      blobs: [],
-      time: new Date(event.ts).toISOString(),
-    };
+  private broadcastIdentity(event: IdentityEvent): void {
+    broadcastIdentity(this.getSocketTargets(), event);
+  }
 
-    return createCommitFrame(message);
+  private broadcastAccount(event: AccountEvent): void {
+    broadcastAccount(this.getSocketTargets(), event);
   }
 
-  /**
-   * Append commit event to buffer with backpressure
-   */
   private appendCommit(event: CommitEvent): void {
     this.buffer.push(event);
 
-    // Implement backpressure: drop oldest events if buffer is full
     if (this.buffer.length > this.maxWindow) {
       const dropped = this.buffer.shift();
       this.droppedFrameCount++;
-      console.warn(`Dropped event seq=${dropped?.seq} due to backpressure (total dropped: ${this.droppedFrameCount})`);
-
-      // Send #info frame to all clients about dropped frames
+      console.warn(
+        `Dropped event seq=${dropped?.seq} due to backpressure (total dropped: ${this.droppedFrameCount})`,
+      );
       this.notifyFramesDropped();
     }
   }
 
-  /**
-   * Notify all clients that frames were dropped
-   */
   private notifyFramesDropped(): void {
-    const infoFrame = createInfoFrame(
+    const bytes = encodeInfoFrame(
       'FramesDropped',
       `${this.droppedFrameCount} frame(s) dropped due to backpressure`,
     );
-    const bytes = infoFrame.toFramedBytes();
 
     for (const [id, client] of Array.from(this.clients.entries())) {
       try {
@@ -556,9 +349,6 @@ export class Sequencer {
     }
   }
 
-  /**
-   * Get metrics
-   */
   getMetrics(): {
     connectedClients: number;
     bufferSize: number;
@@ -572,4 +362,90 @@ export class Sequencer {
       droppedFrames: this.droppedFrameCount,
     };
   }
+
+  async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
+    const client = Array.from(this.clients.values()).find((c) => c.webSocket === ws);
+    if (!client) {
+      console.warn('Received message from unknown WebSocket');
+      return;
+    }
+
+    try {
+      const data = typeof message === 'string' ? message : new TextDecoder().decode(message);
+      if (data === 'ping') ws.send('pong');
+    } catch (error) {
+      console.error('WebSocket message error:', error);
+    }
+  }
+
+  private async handleMetrics(): Promise<Response> {
+    const base = this.getMetrics();
+    let sockets: WebSocket[] = [];
+    try {
+      // workers-types WebSocket misses a few DOM-types members; the values
+      // are wire-compatible at runtime, so widen through unknown.
+      sockets = (this.state.getWebSockets?.() || []) as unknown as WebSocket[];
+    } catch (error) {
+      console.warn('Sequencer: getWebSockets failed in metrics:', error);
+    }
+    const clients = sockets.map((ws) => {
+      let attachment: WebSocketAttachment | undefined;
+      try {
+        attachment = (ws as HibernatableSocket).deserializeAttachment?.();
+      } catch (attachError) {
+        console.warn('Sequencer: deserializeAttachment failed in metrics:', attachError);
+      }
+      return { attachment: attachment ?? null };
+    });
+    const body = {
+      ...base,
+      hibernatedSockets: sockets.length,
+      clients,
+    };
+    return new Response(JSON.stringify(body), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  async webSocketOpen(ws: WebSocket): Promise<void> {
+    console.log(JSON.stringify({ level: 'info', type: 'ws_open', ts: new Date().toISOString() }));
+
+    let cursor: number | undefined;
+    try {
+      const attachment = (ws as HibernatableSocket).deserializeAttachment?.();
+      if (attachment && typeof attachment.cursor === 'number') cursor = attachment.cursor;
+    } catch (attachError) {
+      console.warn('Sequencer: deserializeAttachment failed on open:', attachError);
+    }
+    if (cursor == null) {
+      const client = Array.from(this.clients.values()).find((c) => c.webSocket === ws);
+      if (client) cursor = client.cursor;
+    }
+    if (cursor && cursor > 0) {
+      await this.replayFromCursor(ws, cursor);
+    }
+  }
+
+  async webSocketClose(
+    ws: WebSocket,
+    code: number,
+    reason: string,
+    wasClean: boolean,
+  ): Promise<void> {
+    const entry = Array.from(this.clients.entries()).find(([, c]) => c.webSocket === ws);
+    if (entry) {
+      this.clients.delete(entry[0]);
+      console.log(
+        `Client ${entry[0]} disconnected: code=${code} reason="${reason}" clean=${wasClean}`,
+      );
+    }
+  }
+
+  async webSocketError(ws: WebSocket, error: unknown): Promise<void> {
+    const entry = Array.from(this.clients.entries()).find(([, c]) => c.webSocket === ws);
+    if (entry) {
+      this.clients.delete(entry[0]);
+      console.error(`Client ${entry[0]} error:`, error);
+    }
+  }
 }