bpm-engine 0.1.0

Lightweight embeddable BPM runtime for long-running, stateful workflows with tokens, timers, Saga compensation, and crash recovery
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198

# Database Schema & Transaction Boundaries

> This document defines the **relational database schema** and **transactional rules** for the BPM engine.
> The schema is designed for **high concurrency, crash safety, and optimistic locking**.

---

## 1. Design Principles

- Database is the **source of truth**
- Optimistic locking over pessimistic locking
- Small, bounded transactions
- Explicit state transitions

---

## 2. process_instance

Represents a running process.

```
process_instance
-----------------------------
id (pk)
process_def_id
status            -- Running | Completed | Failed
version            -- optimistic lock
created_at
updated_at
```

Notes:
- Rarely updated after creation
- Not used for execution locking

---

## 3. token

Execution unit and concurrency boundary.

```
token
-----------------------------
id (pk)
instance_id (fk)
node_id
state             -- Ready | Executing | Waiting | Completed | Failed
mode              -- Forward | Compensation
attempt
version            -- optimistic lock
parallel_group_id
created_at
updated_at
```

Indexes:
- (state, updated_at)
- (parallel_group_id)

---

## 4. Token Claim (Critical Path)

Claiming a token is a **single atomic UPDATE**:

```
UPDATE token
SET state = 'Executing',
    version = version + 1
WHERE id = ?
  AND state = 'Ready'
  AND version = ?;
```

Rows affected = 1 → claim success.

---

## 5. event_outbox

Durable event publication.

```
event_outbox
-----------------------------
id (pk)
event_type
payload
status            -- Pending | Published
created_at
```

Guarantees at-least-once delivery.

---

## 6. timer

Persistent timers and delays.

```
timer
-----------------------------
id (pk)
token_id (fk)
due_at
status            -- Scheduled | Fired | Cancelled
created_at
```

Expired timers are safe to re-fire.

---

## 7. compensation_record

Immutable compensation facts.

```
compensation_record
-----------------------------
id (pk)
instance_id
node_id
handler_ref
order
status            -- Pending | Completed | Failed
created_at
```

Never updated except status.

---

## 8. parallel_join

Tracks fork/join completion.

```
parallel_join
-----------------------------
id (pk)
parallel_group_id
expected
joined
```

Join succeeds when `joined == expected`.

---

## 9. Transaction Boundaries

### 9.1 Token Execution Transaction

One transaction per event:

1. Claim token
2. Execute handler
3. Persist results
4. Emit events

No IO inside transaction.

---

### 9.2 Join Update Transaction

Join update must be atomic:

```
UPDATE parallel_join
SET joined = joined + 1
WHERE parallel_group_id = ?
  AND joined < expected;
```

---

## 10. Failure & Recovery Guarantees

- Executing tokens are safe to reset
- Duplicate events are acceptable
- Schema supports deterministic recovery

---

## 11. Relationship to Other Docs

- Execution semantics: `execution-model.md`
- Saga & compensation: `saga.md`
- Recovery behavior: `recovery.md`

---

> **Correct schema makes bugs impossible.**