Giancarmine Salucci
a9429e2118
- Preserve phase results on partial retry and keep interrupted phase context after restart. - Avoid webhook bookkeeping crashes when retention deletes stale jobs. - Add deeper unit, integration, and e2e coverage around queue seams. - Require verify job to pass before publish runs. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
40 lines
1.5 KiB
Markdown
40 lines
1.5 KiB
Markdown
# jobqueue docs
|
|
|
|
Detailed architecture and runtime docs for `jobqueue`.
|
|
|
|
## Doc map
|
|
|
|
| File | Purpose |
|
|
| --- | --- |
|
|
| [`architecture.md`](./architecture.md) | Static architecture, module boundaries, data model, event model, state model |
|
|
| [`runtime-lifecycle.md`](./runtime-lifecycle.md) | Step-by-step runtime behavior from startup through shutdown |
|
|
| [`integration-findings.md`](./integration-findings.md) | Multi-agent scan results, verified bugs, fixes, and remaining behavioral notes |
|
|
| [`jobqueue.c4`](./jobqueue.c4) | LikeC4 source for landscape, container, component, and runtime views |
|
|
|
|
## Mental model
|
|
|
|
`jobqueue` is a **single-process orchestrator** around a SQLite-backed job table.
|
|
|
|
1. Consumer code creates a `JobQueue`.
|
|
2. Jobs are persisted immediately in SQLite.
|
|
3. A pump claims runnable jobs and hands them to a concurrency-limited worker pool.
|
|
4. `PhaseRunner` executes configured phases and reports progress back through `JobQueue`.
|
|
5. `JobQueue` persists each state transition, emits typed events, formats SSE payloads, and optionally sends webhooks.
|
|
6. A retention scheduler can mark old jobs as `stale` and later delete them.
|
|
|
|
## Rendering LikeC4 views
|
|
|
|
The repository stores LikeC4 source in [`jobqueue.c4`](./jobqueue.c4).
|
|
|
|
```bash
|
|
npx likec4 start docs/jobqueue.c4
|
|
```
|
|
|
|
Recommended views in the file:
|
|
|
|
- `index` - system landscape
|
|
- `library` - container view of `jobqueue`
|
|
- `runtime` - internal runtime/component view
|
|
- `enqueue-to-complete` - dynamic happy path
|
|
- `retry-flow` - dynamic retry path
|