chore: import upstream snapshot with attribution

2026-07-13 13:32:57 +08:00
commit cd420f9332
4811 changed files with 884702 additions and 0 deletions
@@ -0,0 +1,46 @@
+# Run Engine 2.0
+
+Core 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.
+
+## Architecture
+
+The `RunEngine` class (`src/engine/index.ts`) orchestrates modular systems:
+
+### Systems (`src/engine/systems/`)
+
+Each system handles one concern:
+- **BatchSystem**: Batch trigger processing with DRR (Deficit Round Robin)
+- **CheckpointSystem**: Execution checkpoints for recovery
+- **DebounceSystem**: Configurable debouncing with delay
+- **DelayedRunSystem**: TTL-based delayed execution
+- **DequeueSystem**: Pulls runs from queue, assigns to workers
+- **EnqueueSystem**: Adds runs to queue with ordering
+- **ExecutionSnapshotSystem**: Stores/restores run state for warm restarts
+- **PendingVersionSystem**: Version management for deployments
+- **RunAttemptSystem**: Individual execution attempts (retries, heartbeats)
+- **TTLSystem**: Automatic run expiration
+- **WaitpointSystem**: Synchronization primitive for waiting between tasks
+
+### Queue and Locking
+
+- **RunQueue** (`src/run-queue/`): Redis-backed fair queue with concurrency management
+- **BatchQueue** (`src/batch-queue/`): Batch processing queue
+- **RunLocker** (`src/locking.ts`): Redis locks preventing concurrent run execution
+
+## Key Design Patterns
+
+- Event-driven via EventBus
+- OpenTelemetry tracer/meter integration
+- Redis for distributed locks and queues
+- Prisma for persistence with read-only replica support (`readOnlyPrisma`)
+
+## Testing
+
+Tests live in `src/engine/tests/` and use testcontainers (Redis + PostgreSQL):
+
+```bash
+cd internal-packages/run-engine
+pnpm run test ./src/engine/tests/ttl.test.ts --run
+```
+
+May need to build dependencies first: `pnpm run build --filter @internal/run-engine`