CLAUDE.md

1# Run Engine 2.0
2 
3Core run lifecycle management system (`@internal/run-engine`). This is where ALL new run lifecycle logic should go - not in `apps/webapp/app/v3/services/` directly.
4 
5## Architecture
6 
7The `RunEngine` class (`src/engine/index.ts`) orchestrates modular systems:
8 
9### Systems (`src/engine/systems/`)
10 
11Each system handles one concern:
12- **BatchSystem**: Batch trigger processing with DRR (Deficit Round Robin)
13- **CheckpointSystem**: Execution checkpoints for recovery
14- **DebounceSystem**: Configurable debouncing with delay
15- **DelayedRunSystem**: TTL-based delayed execution
16- **DequeueSystem**: Pulls runs from queue, assigns to workers
17- **EnqueueSystem**: Adds runs to queue with ordering
18- **ExecutionSnapshotSystem**: Stores/restores run state for warm restarts
19- **PendingVersionSystem**: Version management for deployments
20- **RunAttemptSystem**: Individual execution attempts (retries, heartbeats)
21- **TTLSystem**: Automatic run expiration
22- **WaitpointSystem**: Synchronization primitive for waiting between tasks
23 
24### Queue and Locking
25 
26- **RunQueue** (`src/run-queue/`): Redis-backed fair queue with concurrency management
27- **BatchQueue** (`src/batch-queue/`): Batch processing queue
28- **RunLocker** (`src/locking.ts`): Redis locks preventing concurrent run execution
29 
30## Key Design Patterns
31 
32- Event-driven via EventBus
33- OpenTelemetry tracer/meter integration
34- Redis for distributed locks and queues
35- Prisma for persistence with read-only replica support (`readOnlyPrisma`)
36 
37## Testing
38 
39Tests live in `src/engine/tests/` and use testcontainers (Redis + PostgreSQL):
40 
41```bash
42cd internal-packages/run-engine
43pnpm run test ./src/engine/tests/ttl.test.ts --run
44```
45 
46May need to build dependencies first: `pnpm run build --filter @internal/run-engine`
47