opencode-swarm-plugin 0.18.0 → 0.19.0

package/src/streams/index.ts

@@ -1,5 +1,30 @@
 /**
- * PGLite Event Store Setup
+ * SwarmMail Event Store - PGLite-based event sourcing
+ *
+ * ## Thread Safety
+ *
+ * PGLite runs in-process as a single-threaded SQLite-compatible database.
+ * While Node.js is single-threaded, async operations can interleave.
+ *
+ * **Concurrency Model:**
+ * - Single PGLite instance per project (singleton pattern via LRU cache)
+ * - Transactions provide isolation for multi-statement operations
+ * - appendEvents uses BEGIN/COMMIT for atomic event batches
+ * - Concurrent reads are safe (no locks needed)
+ * - Concurrent writes are serialized by PGLite internally
+ *
+ * **Race Condition Mitigations:**
+ * - File reservations use INSERT with conflict detection
+ * - Sequence numbers are auto-incremented by database
+ * - Materialized views updated within same transaction as events
+ * - Pending instance promises prevent duplicate initialization
+ *
+ * **Known Limitations:**
+ * - No distributed locking (single-process only)
+ * - Large transactions may block other operations
+ * - No connection pooling (embedded database)
+ *
+ * ## Database Setup
  *
  * Embedded PostgreSQL database for event sourcing.
  * No external server required - runs in-process.
@@ -41,6 +66,38 @@ export async function withTimeout<T>(
   return Promise.race([promise, timeout]);
 }
 
+// ============================================================================
+// Performance Monitoring
+// ============================================================================
+
+/** Threshold for slow query warnings in milliseconds */
+const SLOW_QUERY_THRESHOLD_MS = 100;
+
+/**
+ * Execute a database operation with timing instrumentation.
+ * Logs a warning if the operation exceeds SLOW_QUERY_THRESHOLD_MS.
+ *
+ * @param operation - Name of the operation for logging
+ * @param fn - Async function to execute
+ * @returns Result of the function
+ */
+export async function withTiming<T>(
+  operation: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const start = performance.now();
+  try {
+    return await fn();
+  } finally {
+    const duration = performance.now() - start;
+    if (duration > SLOW_QUERY_THRESHOLD_MS) {
+      console.warn(
+        `[SwarmMail] Slow operation: ${operation} took ${duration.toFixed(1)}ms`,
+      );
+    }
+  }
+}
+
 // ============================================================================
 // Debug Logging
 // ============================================================================

package/src/streams/migrations.ts

@@ -1,9 +1,44 @@
 /**
- * Schema Migration System for PGLite Event Store
+ * Schema Migration System
  *
- * Version-based migrations with up/down support.
- * Tracks applied migrations in schema_version table.
- * Idempotent - safe to run multiple times.
+ * Handles database schema evolution for the PGLite event store.
+ *
+ * ## How It Works
+ *
+ * 1. Each migration has a unique version number (incrementing integer)
+ * 2. On startup, `runMigrations()` checks current schema version
+ * 3. Migrations are applied in order until schema is current
+ * 4. Version is stored in `schema_version` table
+ *
+ * ## Adding a New Migration
+ *
+ * ```typescript
+ * // In migrations.ts
+ * export const migrations: Migration[] = [
+ *   // ... existing migrations
+ *   {
+ *     version: 3,
+ *     description: "add_new_column",
+ *     up: `ALTER TABLE events ADD COLUMN new_col TEXT`,
+ *     down: `ALTER TABLE events DROP COLUMN new_col`,
+ *   },
+ * ];
+ * ```
+ *
+ * ## Rollback
+ *
+ * Rollback is supported via `rollbackTo(db, targetVersion)`.
+ * Note: Some migrations may not be fully reversible (data loss).
+ *
+ * ## Best Practices
+ *
+ * - Always test migrations on a copy of production data
+ * - Keep migrations small and focused
+ * - Include both `up` and `down` SQL
+ * - Use transactions for multi-statement migrations
+ * - Document any data transformations
+ *
+ * @module migrations
  */
 import type { PGlite } from "@electric-sql/pglite";
 
@@ -11,10 +46,17 @@ import type { PGlite } from "@electric-sql/pglite";
 // Types
 // ============================================================================
 
+/**
+ * A database migration definition.
+ */
 export interface Migration {
+  /** Unique version number (must be sequential) */
   version: number;
+  /** Human-readable migration description */
   description: string;
+  /** SQL to apply the migration */
   up: string;
+  /** SQL to rollback the migration (best effort) */
   down: string;
 }
 

package/src/streams/store.integration.test.ts

@@ -17,6 +17,7 @@ import {
   readEvents,
   getLatestSequence,
   replayEvents,
+  replayEventsBatched,
   registerAgent,
   sendMessage,
   reserveFiles,
@@ -343,6 +344,115 @@ describe("Event Store", () => {
     });
   });
 
+  describe("replayEventsBatched", () => {
+    it("should replay events in batches with progress tracking", async () => {
+      // Create 50 events
+      for (let i = 0; i < 50; i++) {
+        await registerAgent(
+          "test-project",
+          `Agent${i}`,
+          { taskDescription: `Agent ${i}` },
+          TEST_PROJECT_PATH,
+        );
+      }
+
+      // Manually corrupt the views
+      const db = await getDatabase(TEST_PROJECT_PATH);
+      await db.query("DELETE FROM agents WHERE project_key = 'test-project'");
+
+      // Verify views are empty
+      const empty = await db.query<{ count: string }>(
+        "SELECT COUNT(*) as count FROM agents WHERE project_key = 'test-project'",
+      );
+      expect(parseInt(empty.rows[0]?.count ?? "0")).toBe(0);
+
+      // Track progress
+      const progressUpdates: Array<{
+        processed: number;
+        total: number;
+        percent: number;
+      }> = [];
+
+      // Replay in batches of 10
+      const result = await replayEventsBatched(
+        "test-project",
+        async (_events, progress) => {
+          progressUpdates.push(progress);
+        },
+        { batchSize: 10, clearViews: false },
+        TEST_PROJECT_PATH,
+      );
+
+      // Verify all events replayed
+      expect(result.eventsReplayed).toBe(50);
+
+      // Verify progress updates
+      expect(progressUpdates.length).toBe(5); // 50 events / 10 per batch = 5 batches
+      expect(progressUpdates[0]).toMatchObject({
+        processed: 10,
+        total: 50,
+        percent: 20,
+      });
+      expect(progressUpdates[4]).toMatchObject({
+        processed: 50,
+        total: 50,
+        percent: 100,
+      });
+
+      // Verify views are restored
+      const restored = await db.query<{ count: string }>(
+        "SELECT COUNT(*) as count FROM agents WHERE project_key = 'test-project'",
+      );
+      expect(parseInt(restored.rows[0]?.count ?? "0")).toBe(50);
+    });
+
+    it("should handle zero events gracefully", async () => {
+      const progressUpdates: Array<{
+        processed: number;
+        total: number;
+        percent: number;
+      }> = [];
+
+      const result = await replayEventsBatched(
+        "test-project",
+        async (_events, progress) => {
+          progressUpdates.push(progress);
+        },
+        { batchSize: 10 },
+        TEST_PROJECT_PATH,
+      );
+
+      expect(result.eventsReplayed).toBe(0);
+      expect(progressUpdates.length).toBe(0);
+    });
+
+    it("should use custom batch size", async () => {
+      // Create 25 events
+      for (let i = 0; i < 25; i++) {
+        await registerAgent("test-project", `Agent${i}`, {}, TEST_PROJECT_PATH);
+      }
+
+      const progressUpdates: Array<{
+        processed: number;
+        total: number;
+        percent: number;
+      }> = [];
+
+      // Replay with batch size of 5
+      await replayEventsBatched(
+        "test-project",
+        async (_events, progress) => {
+          progressUpdates.push(progress);
+        },
+        { batchSize: 5, clearViews: false },
+        TEST_PROJECT_PATH,
+      );
+
+      // Should have 5 batches (25 events / 5 per batch)
+      expect(progressUpdates.length).toBe(5);
+    });
+  });
+
   describe("getDatabaseStats", () => {
     it("should return correct counts", async () => {
       await registerAgent("test-project", "Agent1", {}, TEST_PROJECT_PATH);