太好了 👍
那我直接给你一份 **README v1（可直接提交到仓库）**。
这份 README 的目标只有一个：
> **让一个懂系统 / 后端 / Rust 的人，
> 3 分钟理解你在做什么，
> 并意识到：这是个“认真做正确性的 BPM 引擎”。**
你可以**原样使用**，也可以按需要微调语气。
---
```md
# bpm-engine
A native Rust BPM engine with strong correctness guarantees.
This project focuses on **execution semantics, persistence correctness, and crash safety**,
rather than UI or low-code features.
It is designed as a **token-driven, persistence-first BPM engine** with deterministic replay
and formally defined invariants.
---
## What is this?
`bpm-engine` is a **workflow / BPM execution engine** implemented in Rust.
At its core, it executes processes as **persistent token state machines**, where:
- Every execution step is driven by database state
- Every state transition is recorded as history
- Every execution can be replayed and verified
- Concurrency, retries, and crashes are first-class concerns
This makes the engine suitable for **long-running, distributed, and failure-prone workflows**.
---
## Why another BPM engine?
Most BPM engines optimize for **features and modeling UX**.
This engine optimizes for **correctness**.
Specifically:
- Token state is **explicit and persisted**
- Execution is **crash-safe by construction**
- External tasks use **lease-based execution**
- Timers are **fully persistent**
- All executions are **auditable and replayable**
- Core behavior is protected by **formal invariants**
If you care about _why_ a process reached a certain state — not just _that_ it did — this engine
is for you.
---
## Core Concepts
### Process & Instance
- A **process definition** is an immutable execution graph
- A **process instance** is a container for runtime tokens
### Token
A token represents a unit of execution.
- Each token has a clear lifecycle
- State transitions are persisted
- Parallelism is modeled via token forking and joining
### External Task
External tasks allow work to be executed by external workers:
- Workers fetch tasks by topic
- Tasks are protected by **leases**
- Retries, timeouts, and crashes are handled by the engine
### Timer
Timers are persistent and scheduler-driven:
- No in-memory timers
- Safe across restarts
- Naturally scalable
### History & Replay
- Every state change emits a history event
- Execution can be replayed deterministically
- History can be used for debugging, auditing, and verification
### Invariants
The engine enforces formal invariants such as:
- A token can only reach a final state once
- Join nodes only complete when all branches complete
- External tasks have exactly one owner at a time
- Retries are monotonic
---
## Architecture Overview
```
+-------------------+
| Scheduler |
| Token Executor |
| Invariants |
| ------------------- |
```
|
v
```
+-------------------+
| Runtime Tables |
| History Tables |
| Timers |
| +-------------------+ |
External Workers
(fetch / lock / complete via API)
````
The database is the **single source of truth**.
The engine can always recover by re-running its schedulers.
---
## Getting Started (5 minutes)
> Requirements:
> - Rust (stable)
> - PostgreSQL
> - Docker (optional)
```bash
git clone https://github.com/fanjia1024/bpm-engine.git
cd bpm-engine
docker compose up -d
cargo run --example simple_process
````
This will:
1. Start a Postgres instance
2. Deploy a sample process
3. Execute it end-to-end
---
## Example: External Task Worker
```rust
#[external_task(topic = "payment")]
async fn handle_payment(ctx: TaskContext) -> Result<()> {
// business logic
ctx.complete().await?;
Ok(())
}
```
Workers:
- Are stateless
- Can crash safely
- Can be horizontally scaled
---
## Guarantees
This engine provides the following guarantees:
- Exactly-once token completion
- Crash-safe execution
- Deterministic replay
- Persistent timers
- Formal invariants checked in tests
These guarantees are **design goals**, not best-effort behavior.
---
## Project Status
This project is in **active development**.
- Core execution semantics are stable
- APIs may evolve
- Not yet recommended for mission-critical production use
That said, the engine is already suitable for:
- Research
- Prototyping
- Internal systems
- Correctness-focused experimentation
---
## Roadmap
- Worker SDK stabilization (Rust / Python)
- Read-only execution inspector (Cockpit-like UI)
- More invariant coverage
- Documentation & examples
---
## Contributing
Contributions are welcome.
Areas where help is especially valuable:
- Testing and invariant cases
- Documentation
- Worker SDK ergonomics
- Visualization tools
Please see `CONTRIBUTING.md`.
---
## License
Apache License 2.0
```
---
## 下一步建议（很关键）
你现在**立刻可以做的 3 件小而高价值的事**：
1. ✅ 把这份 README 提交
2. ✅ 补一个 `examples/simple_process.rs`
3. ✅ 在 README 里加一张 **Token 生命周期图**
接下来如果你愿意，我可以直接帮你：
- ✍️ 写 **`docs/invariants.md`**（非常吸引高手）
- 🧪 设计 **“Invariant Test Suite” 展示页**
- 🎯 帮你写 **开源发布帖（HN / Reddit / Rust 社区）**
你随便选一个方向，我继续陪你把这个项目**真正推向外部世界**。
```