swarm-mail 0.4.0 → 1.0.0

package/README.md

@@ -47,6 +47,9 @@ Event sourcing primitives for multi-agent coordination. Local-first, no external
 │  ├── DurableCursor - Checkpointed stream reader            │
 │  └── DurableDeferred - Distributed promise                 │
 │                                                             │
+│  MEMORY                                                     │
+│  └── Semantic Memory - Vector embeddings (pgvector/Ollama) │
+│                                                             │
 │  STORAGE                                                    │
 │  └── PGLite (Embedded Postgres) + Migrations               │
 └─────────────────────────────────────────────────────────────┘
@@ -136,6 +139,90 @@ const swarmMail = await getSwarmMail('/my/project') // persistent
 const swarmMail = await createInMemorySwarmMail() // in-memory
 ```
 
+## Deployment
+
+### Connection Modes
+
+#### Daemon Mode (Default)
+
+By default, swarm-mail starts an in-process `PGLiteSocketServer` when you call `getSwarmMail()`. All database operations go through this server, preventing multi-process corruption.
+
+```typescript
+import { getSwarmMail } from 'swarm-mail'
+
+// Default: starts daemon automatically
+const swarmMail = await getSwarmMail('/my/project')
+
+// Keep alive - handles cleanup on shutdown
+process.on('SIGTERM', async () => {
+  await swarmMail.close() // Flushes WAL, closes cleanly
+  process.exit(0)
+})
+```
+
+**Why daemon mode is the default:**
+
+- **No external dependencies** - Uses `@electric-sql/pglite-socket` in-process
+- **Multi-process safe** - One PGLite instance, multiple clients can connect safely
+- **WAL safety** - Single process prevents WAL accumulation from multiple instances
+- **Proper cleanup** - Graceful shutdown triggers checkpoint, preventing unclean state
+- **Resource efficiency** - One PGLite instance shared across operations
+
+#### Embedded Mode (Opt-out)
+
+For single-process use cases where you're certain only one process will access the database, you can opt out of daemon mode:
+
+```bash
+SWARM_MAIL_SOCKET=false
+```
+
+⚠️ **Warning:** Embedded mode is NOT safe for multi-process access. PGLite uses a single connection, so concurrent processes will cause database corruption. Use only when you're absolutely certain only one process will access the database
+
+### WAL Safety Features
+
+PGLite uses PostgreSQL's Write-Ahead Log (WAL) for durability. Swarm Mail includes safeguards against WAL bloat:
+
+**Automatic checkpointing:**
+```typescript
+// After batch operations, force WAL flush
+await db.checkpoint()
+```
+
+**Health monitoring:**
+```typescript
+// Check WAL size (default threshold: 100MB)
+const health = await swarmMail.healthCheck({ walThresholdMb: 100 })
+
+if (!health.walHealth?.healthy) {
+  console.warn(health.walHealth?.message)
+  // "WAL size 120MB exceeds 100MB threshold (15 files)"
+}
+
+// Get detailed stats
+const stats = await swarmMail.getDatabaseStats()
+// { connected: true, wal: { size: 120_000_000, fileCount: 15 } }
+```
+
+**When to checkpoint manually:**
+
+- After migrations: `await swarmMail.runMigrations(); await db.checkpoint()`
+- After bulk event appends (100+ events)
+- Before long-running operations
+
+### Ephemeral Instances (Testing)
+
+For tests, create isolated in-memory instances:
+
+```typescript
+import { createInMemorySwarmMail } from 'swarm-mail'
+
+const swarmMail = await createInMemorySwarmMail('test-id')
+// ... run tests ...
+await swarmMail.close()
+```
+
+**Don't use ephemeral instances in production** - multiple short-lived processes compound WAL accumulation since each instance creates new PGLite connections without coordinated cleanup.
+
 ## Event Types
 
 ```typescript
@@ -183,12 +270,46 @@ Materialized views derived from events:
 | `swarm_contexts`    | Checkpoint state for recovery      |
 | `eval_records`      | Outcome data for learning          |
 
+### Semantic Memory
+
+Persistent, searchable storage for agent learnings:
+
+```typescript
+import { createMemoryAdapter } from 'swarm-mail/memory'
+
+const swarmMail = await getSwarmMail('/my/project')
+const db = await swarmMail.getDatabase()
+const memory = await createMemoryAdapter(db)
+
+// Store a learning
+const { id } = await memory.store(
+  "OAuth refresh tokens need 5min buffer before expiry...",
+  { tags: "auth,tokens,debugging" }
+)
+
+// Search by meaning (vector similarity)
+const results = await memory.find("token refresh issues")
+
+// Check Ollama health
+const health = await memory.checkHealth()
+// { ollama: true, model: "mxbai-embed-large" }
+```
+
+> **Note:** Requires [Ollama](https://ollama.ai/) for vector embeddings. Falls back to full-text search if unavailable.
+>
+> ```bash
+> ollama pull mxbai-embed-large
+> ```
+
+> **Deprecation Notice:** The standalone [semantic-memory MCP server](https://github.com/joelhooks/semantic-memory) is deprecated. Use the embedded memory in swarm-mail instead - same API, single PGLite instance, no separate process.
+
 ## Architecture
 
 - **Append-only log** - Events are immutable, projections are derived
 - **Local-first** - PGLite embedded Postgres, no external servers
 - **Effect-TS** - Type-safe, composable, testable
 - **Exactly-once** - DurableCursor checkpoints position
+- **Semantic memory** - Vector embeddings with pgvector + Ollama
 
 ## API Reference
 

package/bin/daemon-cli.ts

@@ -2,10 +2,10 @@
 /**
  * swarm-mail-daemon CLI
  *
- * Command-line interface for managing the swarm-mail pglite-server daemon.
+ * Command-line interface for managing the in-process PGLiteSocketServer daemon.
  *
  * Commands:
- *   start [options]  - Start the daemon
+ *   start [options]  - Start the in-process daemon
  *   stop             - Stop the daemon
  *   status           - Show daemon status
  *
@@ -65,13 +65,13 @@ function info(msg: string) {
 
 function showHelp() {
 	console.log(`
-${colors.bold}swarm-mail-daemon${colors.reset} - Manage pglite-server daemon for swarm-mail
+${colors.bold}swarm-mail-daemon${colors.reset} - Manage in-process PGLiteSocketServer daemon
 
 ${colors.bold}USAGE${colors.reset}
   swarm-mail-daemon <command> [options]
 
 ${colors.bold}COMMANDS${colors.reset}
-  start [options]  Start the daemon
+  start [options]  Start the in-process daemon
   stop             Stop the daemon
   status           Show daemon status
 

package/dist/beads/adapter.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Beads Adapter - Factory for creating BeadsAdapter instances
+ *
+ * This file implements the adapter pattern for beads event sourcing,
+ * enabling dependency injection of the database.
+ *
+ * ## Design Pattern
+ * - Accept DatabaseAdapter via factory parameter
+ * - Return BeadsAdapter interface
+ * - Delegate to store.ts for event operations
+ * - Delegate to projections.ts for queries
+ * - No direct database access (all via adapter)
+ *
+ * ## Usage
+ * ```typescript
+ * import { wrapPGlite } from '@opencode/swarm-mail/pglite';
+ * import { createBeadsAdapter } from '@opencode/swarm-mail/beads';
+ *
+ * const pglite = new PGlite('./streams.db');
+ * const db = wrapPGlite(pglite);
+ * const beads = createBeadsAdapter(db, '/path/to/project');
+ *
+ * // Use the adapter
+ * await beads.createBead(projectKey, { title: "Task", type: "task", priority: 2 });
+ * const bead = await beads.getBead(projectKey, "bd-123");
+ * ```
+ */
+import type { DatabaseAdapter } from "../types/database.js";
+import type { BeadsAdapter } from "../types/beads-adapter.js";
+/**
+ * Create a BeadsAdapter instance
+ *
+ * @param db - DatabaseAdapter instance (PGLite, SQLite, PostgreSQL, etc.)
+ * @param projectKey - Project identifier (typically the project path)
+ * @returns BeadsAdapter interface
+ */
+export declare function createBeadsAdapter(db: DatabaseAdapter, projectKey: string): BeadsAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/beads/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/beads/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AA6B9D;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,GACjB,YAAY,CAkiBd"}

package/dist/beads/blocked-cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Blocked Beads Cache Management
+ *
+ * Convenience re-exports for blocked cache operations.
+ * The actual implementation is in dependencies.ts to avoid circular dependencies.
+ *
+ * ## Cache Strategy
+ * - blocked_beads_cache table stores bead_id → blocker_ids[]
+ * - Rebuilt when dependencies change or bead status changes
+ * - Enables fast "ready work" queries without recursive CTEs
+ *
+ * ## Performance
+ * - Cache rebuild: <50ms for typical projects
+ * - Ready work query: 25x faster with cache (752ms → 29ms on 10K beads)
+ *
+ * Reference: steveyegge/beads/internal/storage/sqlite/blocked_cache.go
+ *
+ * @module beads/blocked-cache
+ */
+export { rebuildBeadBlockedCache, rebuildAllBlockedCaches, invalidateBlockedCache, } from "./dependencies.js";
+//# sourceMappingURL=blocked-cache.d.ts.map

package/dist/beads/blocked-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocked-cache.d.ts","sourceRoot":"","sources":["../../src/beads/blocked-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC"}

package/dist/beads/comments.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Comment Operations
+ *
+ * Comment management with threading support.
+ * Comments can have parent_id for nested discussions.
+ *
+ * Reference: steveyegge/beads/internal/storage/sqlite/comments.go
+ *
+ * @module beads/comments
+ */
+import type { DatabaseAdapter } from "../types/database.js";
+import type { BeadComment } from "../types/beads-adapter.js";
+/**
+ * Get a specific comment by ID
+ */
+export declare function getCommentById(db: DatabaseAdapter, commentId: number): Promise<BeadComment | null>;
+/**
+ * Get comment thread (comment + all replies)
+ */
+export declare function getCommentThread(db: DatabaseAdapter, rootCommentId: number): Promise<BeadComment[]>;
+//# sourceMappingURL=comments.d.ts.map

package/dist/beads/comments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/beads/comments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D;;GAEG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,eAAe,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAM7B;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,eAAe,EACnB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,WAAW,EAAE,CAAC,CAgBxB"}

package/dist/beads/dependencies.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Dependency Graph Operations
+ *
+ * Provides dependency management with cycle detection and blocked bead tracking.
+ *
+ * ## Dependency Types
+ * - **blocks**: Hard dependency - target must be closed before source can start
+ * - **blocked-by**: Inverse of blocks (computed, not stored)
+ * - **related**: Soft relationship - doesn't affect ready state
+ * - **discovered-from**: Tracking relationship - found while working on another bead
+ *
+ * ## Cycle Prevention
+ * All dependency types are checked for cycles to maintain a DAG (Directed Acyclic Graph).
+ * This ensures:
+ * - Ready work calculation works correctly
+ * - Dependency traversal doesn't loop
+ * - Semantic clarity (no circular dependencies)
+ *
+ * Reference: steveyegge/beads/internal/storage/sqlite/dependencies.go
+ *
+ * @module beads/dependencies
+ */
+import type { DatabaseAdapter } from "../types/database.js";
+/**
+ * Check if adding a dependency would create a cycle
+ *
+ * Uses recursive CTE to traverse from dependsOnId to see if we can reach beadId.
+ * If yes, adding "beadId depends on dependsOnId" would complete a cycle.
+ */
+export declare function wouldCreateCycle(db: DatabaseAdapter, beadId: string, dependsOnId: string): Promise<boolean>;
+/**
+ * Get all open blockers for a bead (including transitive)
+ *
+ * Returns bead IDs of all beads blocking this one that aren't closed.
+ * Only considers "blocks" relationship type.
+ */
+export declare function getOpenBlockers(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<string[]>;
+/**
+ * Rebuild blocked cache for a specific bead
+ *
+ * Finds all open blockers and updates the cache.
+ * If no open blockers, removes from cache (bead is unblocked).
+ */
+export declare function rebuildBeadBlockedCache(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<void>;
+/**
+ * Rebuild blocked cache for all beads in a project
+ *
+ * Used after bulk operations or status changes that affect blocking.
+ */
+export declare function rebuildAllBlockedCaches(db: DatabaseAdapter, projectKey: string): Promise<void>;
+/**
+ * Invalidate blocked cache when dependencies change
+ *
+ * Marks beads as needing cache rebuild.
+ * In this simple implementation, we just rebuild immediately.
+ */
+export declare function invalidateBlockedCache(db: DatabaseAdapter, projectKey: string, beadId: string): Promise<void>;
+//# sourceMappingURL=dependencies.d.ts.map

package/dist/beads/dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../../src/beads/dependencies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAI5D;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,EAAE,EAAE,eAAe,EACnB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,OAAO,CAAC,CA6BlB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,EAAE,CAAC,CAwBnB;AAED;;;;;GAKG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAmBf;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,EAAE,EAAE,eAAe,EACnB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAYf"}

package/dist/beads/events.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Bead Event Types - Minimal type definitions for swarm-mail
+ *
+ * These are simplified type definitions that match the bead-events from
+ * opencode-swarm-plugin but avoid cross-package TypeScript imports.
+ *
+ * The actual event schemas with Zod validation live in:
+ * packages/opencode-swarm-plugin/src/schemas/bead-events.ts
+ *
+ * This file provides just enough type information for the store to work.
+ */
+/**
+ * Base bead event (all events extend this)
+ */
+export interface BaseBeadEvent {
+    id?: number;
+    type: string;
+    project_key: string;
+    bead_id: string;
+    timestamp: number;
+    sequence?: number;
+}
+/**
+ * Union of all bead event types
+ *
+ * This matches the discriminated union in bead-events.ts but as pure TypeScript
+ */
+export type BeadEvent = BeadCreatedEvent | BeadUpdatedEvent | BeadStatusChangedEvent | BeadClosedEvent | BeadReopenedEvent | BeadDeletedEvent | BeadDependencyAddedEvent | BeadDependencyRemovedEvent | BeadLabelAddedEvent | BeadLabelRemovedEvent | BeadCommentAddedEvent | BeadCommentUpdatedEvent | BeadCommentDeletedEvent | BeadEpicChildAddedEvent | BeadEpicChildRemovedEvent | BeadEpicClosureEligibleEvent | BeadAssignedEvent | BeadWorkStartedEvent | BeadCompactedEvent;
+export interface BeadCreatedEvent extends BaseBeadEvent {
+    type: "bead_created";
+    title: string;
+    description?: string;
+    issue_type: "bug" | "feature" | "task" | "epic" | "chore";
+    priority: number;
+    parent_id?: string;
+    created_by?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface BeadUpdatedEvent extends BaseBeadEvent {
+    type: "bead_updated";
+    updated_by?: string;
+    changes: {
+        title?: {
+            old: string;
+            new: string;
+        };
+        description?: {
+            old: string;
+            new: string;
+        };
+        priority?: {
+            old: number;
+            new: number;
+        };
+    };
+}
+export interface BeadStatusChangedEvent extends BaseBeadEvent {
+    type: "bead_status_changed";
+    from_status: "open" | "in_progress" | "blocked" | "closed" | "tombstone";
+    to_status: "open" | "in_progress" | "blocked" | "closed" | "tombstone";
+    changed_by?: string;
+    reason?: string;
+}
+export interface BeadClosedEvent extends BaseBeadEvent {
+    type: "bead_closed";
+    reason: string;
+    closed_by?: string;
+    files_touched?: string[];
+    duration_ms?: number;
+}
+export interface BeadReopenedEvent extends BaseBeadEvent {
+    type: "bead_reopened";
+    reason?: string;
+    reopened_by?: string;
+}
+export interface BeadDeletedEvent extends BaseBeadEvent {
+    type: "bead_deleted";
+    reason?: string;
+    deleted_by?: string;
+}
+export interface BeadDependencyAddedEvent extends BaseBeadEvent {
+    type: "bead_dependency_added";
+    dependency: {
+        target: string;
+        type: "blocks" | "blocked-by" | "related" | "discovered-from";
+    };
+    added_by?: string;
+    reason?: string;
+}
+export interface BeadDependencyRemovedEvent extends BaseBeadEvent {
+    type: "bead_dependency_removed";
+    dependency: {
+        target: string;
+        type: "blocks" | "blocked-by" | "related" | "discovered-from";
+    };
+    removed_by?: string;
+    reason?: string;
+}
+export interface BeadLabelAddedEvent extends BaseBeadEvent {
+    type: "bead_label_added";
+    label: string;
+    added_by?: string;
+}
+export interface BeadLabelRemovedEvent extends BaseBeadEvent {
+    type: "bead_label_removed";
+    label: string;
+    removed_by?: string;
+}
+export interface BeadCommentAddedEvent extends BaseBeadEvent {
+    type: "bead_comment_added";
+    comment_id?: number;
+    author: string;
+    body: string;
+    parent_comment_id?: number;
+    metadata?: Record<string, unknown>;
+}
+export interface BeadCommentUpdatedEvent extends BaseBeadEvent {
+    type: "bead_comment_updated";
+    comment_id: number;
+    old_body: string;
+    new_body: string;
+    updated_by: string;
+}
+export interface BeadCommentDeletedEvent extends BaseBeadEvent {
+    type: "bead_comment_deleted";
+    comment_id: number;
+    deleted_by: string;
+    reason?: string;
+}
+export interface BeadEpicChildAddedEvent extends BaseBeadEvent {
+    type: "bead_epic_child_added";
+    child_id: string;
+    child_index?: number;
+    added_by?: string;
+}
+export interface BeadEpicChildRemovedEvent extends BaseBeadEvent {
+    type: "bead_epic_child_removed";
+    child_id: string;
+    removed_by?: string;
+    reason?: string;
+}
+export interface BeadEpicClosureEligibleEvent extends BaseBeadEvent {
+    type: "bead_epic_closure_eligible";
+    child_ids: string[];
+    total_duration_ms?: number;
+    all_files_touched?: string[];
+}
+export interface BeadAssignedEvent extends BaseBeadEvent {
+    type: "bead_assigned";
+    agent_name: string;
+    task_description?: string;
+}
+export interface BeadWorkStartedEvent extends BaseBeadEvent {
+    type: "bead_work_started";
+    agent_name: string;
+    reserved_files?: string[];
+}
+export interface BeadCompactedEvent extends BaseBeadEvent {
+    type: "bead_compacted";
+    events_archived: number;
+    new_start_sequence: number;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/beads/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/beads/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAEjB,gBAAgB,GAChB,gBAAgB,GAChB,sBAAsB,GACtB,eAAe,GACf,iBAAiB,GACjB,gBAAgB,GAEhB,wBAAwB,GACxB,0BAA0B,GAE1B,mBAAmB,GACnB,qBAAqB,GAErB,qBAAqB,GACrB,uBAAuB,GACvB,uBAAuB,GAEvB,uBAAuB,GACvB,yBAAyB,GACzB,4BAA4B,GAE5B,iBAAiB,GACjB,oBAAoB,GAEpB,kBAAkB,CAAC;AAMvB,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,IAAI,EAAE,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,IAAI,EAAE,cAAc,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE;QACP,KAAK,CAAC,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC;QACrC,WAAW,CAAC,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC;QAC3C,QAAQ,CAAC,EAAE;YAAE,GAAG,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC;KACzC,CAAC;CACH;AAED,MAAM,WAAW,sBAAuB,SAAQ,aAAa;IAC3D,IAAI,EAAE,qBAAqB,CAAC;IAC5B,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;IACzE,SAAS,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,IAAI,EAAE,eAAe,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,IAAI,EAAE,cAAc,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD,MAAM,WAAW,wBAAyB,SAAQ,aAAa;IAC7D,IAAI,EAAE,uBAAuB,CAAC;IAC9B,UAAU,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,iBAAiB,CAAC;KAC/D,CAAC;IACF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BAA2B,SAAQ,aAAa;IAC/D,IAAI,EAAE,yBAAyB,CAAC;IAChC,UAAU,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,QAAQ,GAAG,YAAY,GAAG,SAAS,GAAG,iBAAiB,CAAC;KAC/D,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD,MAAM,WAAW,mBAAoB,SAAQ,aAAa;IACxD,IAAI,EAAE,kBAAkB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,IAAI,EAAE,oBAAoB,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD,MAAM,WAAW,qBAAsB,SAAQ,aAAa;IAC1D,IAAI,EAAE,oBAAoB,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D,IAAI,EAAE,sBAAsB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D,IAAI,EAAE,sBAAsB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD,MAAM,WAAW,uBAAwB,SAAQ,aAAa;IAC5D,IAAI,EAAE,uBAAuB,CAAC;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,yBAA0B,SAAQ,aAAa;IAC9D,IAAI,EAAE,yBAAyB,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,4BAA6B,SAAQ,aAAa;IACjE,IAAI,EAAE,4BAA4B,CAAC;IACnC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAMD,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,IAAI,EAAE,eAAe,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,IAAI,EAAE,mBAAmB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAMD,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACvD,IAAI,EAAE,gBAAgB,CAAC;IACvB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,MAAM,CAAC;CAC5B"}

package/dist/beads/flush-manager.d.ts

@@ -0,0 +1,71 @@
+/**
+ * FlushManager - Debounced JSONL export to file
+ *
+ * Automatically exports dirty beads to a JSONL file on a debounced timer.
+ * Prevents excessive writes while ensuring changes are persisted.
+ *
+ * Based on steveyegge/beads flush_manager.go
+ *
+ * @module beads/flush-manager
+ */
+import type { BeadsAdapter } from "../types/beads-adapter.js";
+export interface FlushManagerOptions {
+    adapter: BeadsAdapter;
+    projectKey: string;
+    outputPath: string;
+    debounceMs?: number;
+    onFlush?: (result: FlushResult) => void;
+}
+export interface FlushResult {
+    beadsExported: number;
+    bytesWritten: number;
+    duration: number;
+}
+/**
+ * FlushManager handles debounced export of dirty beads to JSONL
+ *
+ * Usage:
+ * ```ts
+ * const manager = new FlushManager({
+ *   adapter,
+ *   projectKey: "/path/to/project",
+ *   outputPath: ".beads/issues.jsonl",
+ *   debounceMs: 30000,
+ * });
+ *
+ * // Schedule flushes as beads change
+ * manager.scheduleFlush();
+ *
+ * // Clean up
+ * manager.stop();
+ * ```
+ */
+export declare class FlushManager {
+    private adapter;
+    private projectKey;
+    private outputPath;
+    private debounceMs;
+    private onFlush?;
+    private timer;
+    private flushing;
+    constructor(options: FlushManagerOptions);
+    /**
+     * Schedule a flush (debounced)
+     *
+     * If a flush is already scheduled, resets the timer.
+     */
+    scheduleFlush(): void;
+    /**
+     * Force immediate flush
+     *
+     * Exports all dirty beads to the output file.
+     */
+    flush(): Promise<FlushResult>;
+    /**
+     * Stop the flush manager
+     *
+     * Clears any pending timers. Does NOT flush pending changes.
+     */
+    stop(): void;
+}
+//# sourceMappingURL=flush-manager.d.ts.map

package/dist/beads/flush-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flush-manager.d.ts","sourceRoot":"","sources":["../../src/beads/flush-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAI9D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,OAAO,CAAC,CAAgC;IAChD,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,EAAE,mBAAmB;IAQxC;;;;OAIG;IACH,aAAa,IAAI,IAAI;IAcrB;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IA8DnC;;;;OAIG;IACH,IAAI,IAAI,IAAI;CAMb"}

package/dist/beads/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Beads Module - Event-sourced issue tracking
+ *
+ * Exports:
+ * - BeadsAdapter interface and types
+ * - Migration definitions
+ * - Projection functions
+ * - Store operations (append, read, replay)
+ * - Event type definitions
+ *
+ * @module beads
+ */
+export type { Bead, BeadAdapter, BeadComment, BeadDependency, BeadLabel, BeadsAdapter, BeadsAdapterFactory, BeadsSchemaAdapter, BeadStatus, BeadType, CommentAdapter, CreateBeadOptions, DependencyAdapter, DependencyRelationship, EpicAdapter, LabelAdapter, QueryAdapter, QueryBeadsOptions, UpdateBeadOptions, } from "../types/beads-adapter.js";
+export type { BeadEvent, BaseBeadEvent, BeadCreatedEvent, BeadUpdatedEvent, BeadStatusChangedEvent, BeadClosedEvent, BeadReopenedEvent, BeadDeletedEvent, BeadDependencyAddedEvent, BeadDependencyRemovedEvent, BeadLabelAddedEvent, BeadLabelRemovedEvent, BeadCommentAddedEvent, BeadCommentUpdatedEvent, BeadCommentDeletedEvent, BeadEpicChildAddedEvent, BeadEpicChildRemovedEvent, BeadEpicClosureEligibleEvent, BeadAssignedEvent, BeadWorkStartedEvent, BeadCompactedEvent, } from "./events.js";
+export { createBeadsAdapter } from "./adapter.js";
+export { beadsMigration, beadsMigrations } from "./migrations.js";
+export { appendBeadEvent, readBeadEvents, replayBeadEvents, type ReadBeadEventsOptions, } from "./store.js";
+export { clearAllDirtyBeads, clearDirtyBead, getBead, getBlockedBeads, getBlockers, getComments, getDependencies, getDependents, getDirtyBeads, getInProgressBeads, getLabels, getNextReadyBead, isBlocked, markBeadDirty, queryBeads, updateProjections, } from "./projections.js";
+export { wouldCreateCycle, getOpenBlockers, rebuildBeadBlockedCache, rebuildAllBlockedCaches, invalidateBlockedCache, } from "./dependencies.js";
+export { getBeadsByLabel, getAllLabels, } from "./labels.js";
+export { getCommentById, getCommentThread, } from "./comments.js";
+export { exportToJSONL, exportDirtyBeads, importFromJSONL, parseJSONL, serializeToJSONL, computeContentHash, type BeadExport, type ExportOptions, type ImportOptions, type ImportResult, } from "./jsonl.js";
+export { FlushManager, type FlushManagerOptions, type FlushResult, } from "./flush-manager.js";
+export { merge3Way, mergeJsonl, isTombstone, isExpiredTombstone, DEFAULT_TOMBSTONE_TTL_MS, MIN_TOMBSTONE_TTL_MS, CLOCK_SKEW_GRACE_MS, STATUS_TOMBSTONE, type IssueKey, type MergeResult, type MergeOptions, } from "./merge.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/beads/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/beads/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,YAAY,EACV,IAAI,EACJ,WAAW,EACX,WAAW,EACX,cAAc,EACd,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,EACV,QAAQ,EACR,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,sBAAsB,EACtB,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,0BAA0B,EAC1B,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,yBAAyB,EACzB,4BAA4B,EAC5B,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlE,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,KAAK,qBAAqB,GAC3B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,eAAe,EACf,WAAW,EACX,WAAW,EACX,eAAe,EACf,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,SAAS,EACT,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,UAAU,EACV,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,eAAe,EACf,YAAY,GACb,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,cAAc,EACd,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,YAAY,EACZ,KAAK,mBAAmB,EACxB,KAAK,WAAW,GACjB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EACL,SAAS,EACT,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,EACpB,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,YAAY,CAAC"}