feat(werkbank): Mongo-backed job queue with lease + visibility timeout (WB-02) #206

2026-07-17T09:07:48Z

sharang commented

2026-07-17 09:07:48 +00:00

Implements sharang/werkbank#3 — the control-plane pull queue behind the Werkbank runner flow.

`JobQueue` (over a `werkbank_jobs` collection)

enqueue — idempotent by job id (unique index; a duplicate is a no-op).
lease — atomic find-and-modify of the oldest queued job the runner can run, matched by executor and by labels (the job's labels must be a subset of the runner's; empty/absent matches any). Returns the job + a lease token and bumps attempts.
heartbeat — extends the lease, flips leased→running, and surfaces a cancel request. None means the lease was lost (token mismatch / already terminal) → the runner abandons the work.
complete — records the terminal result, token-guarded and only from an active state, so it's idempotent (a late/duplicate submission matches nothing).
cancel — a still-queued job goes straight to cancelled; an in-flight one is flagged so the runner sees it on its next heartbeat.
sweep_expired — the visibility timeout: expired leases return to queued, or become expired once attempts hit the max — so a crashed runner's job recovers.

Every transition is a single atomic Mongo update guarded by the lease token, so two runners can never both own a job. Every operation takes an explicit now for deterministic tests.

Contract + schema

Adds JobRecord / LeasedJob / HeartbeatAck to compliance-core::models::werkbank (timestamps persist as BSON dates so the FIFO/expiry range queries compare correctly), plus the three werkbank_jobs indexes (unique job.id; status+executor+created_at; status+lease_expires_at).

Tests

5 integration against a real MongoDB — idempotent enqueue, executor+label matching + FIFO ordering, heartbeat extend/cancel, token-guarded idempotent complete, and sweep requeue→expire. They skip cleanly when no Mongo is reachable (TEST_MONGODB_URI, defaults to the local dev cluster). Plus 2 unit tests. All green locally against certifai-mongo-1; clippy (agent + core) + fmt clean.

Note: the runner-facing HTTP transport (so a remote runner can reach this queue) and the runner itself are WB-03/WB-04.

🤖 Generated with Claude Code

Implements sharang/werkbank#3 — the control-plane pull queue behind the Werkbank runner flow. ## `JobQueue` (over a `werkbank_jobs` collection) - **`enqueue`** — idempotent by job id (unique index; a duplicate is a no-op). - **`lease`** — atomic find-and-modify of the oldest `queued` job the runner can run, matched by **executor** and by **labels** (the job's labels must be a subset of the runner's; empty/absent matches any). Returns the job + a lease token and bumps `attempts`. - **`heartbeat`** — extends the lease, flips `leased`→`running`, and surfaces a cancel request. `None` means the lease was lost (token mismatch / already terminal) → the runner abandons the work. - **`complete`** — records the terminal result, token-guarded and only from an active state, so it's **idempotent** (a late/duplicate submission matches nothing). - **`cancel`** — a still-`queued` job goes straight to `cancelled`; an in-flight one is flagged so the runner sees it on its next heartbeat. - **`sweep_expired`** — the **visibility timeout**: expired leases return to `queued`, or become `expired` once `attempts` hit the max — so a crashed runner's job recovers. Every transition is a single atomic Mongo update guarded by the lease token, so two runners can never both own a job. Every operation takes an explicit `now` for deterministic tests. ## Contract + schema Adds `JobRecord` / `LeasedJob` / `HeartbeatAck` to `compliance-core::models::werkbank` (timestamps persist as BSON dates so the FIFO/expiry range queries compare correctly), plus the three `werkbank_jobs` indexes (unique `job.id`; `status+executor+created_at`; `status+lease_expires_at`). ## Tests **5 integration** against a real MongoDB — idempotent enqueue, executor+label matching + FIFO ordering, heartbeat extend/cancel, token-guarded idempotent complete, and sweep requeue→expire. They **skip cleanly** when no Mongo is reachable (`TEST_MONGODB_URI`, defaults to the local dev cluster). Plus **2 unit** tests. All green locally against `certifai-mongo-1`; clippy (agent + core) + fmt clean. Note: the runner-facing HTTP transport (so a remote runner can reach this queue) and the runner itself are WB-03/WB-04. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

sharang added 1 commit 2026-07-17 09:07:49 +00:00

feat(werkbank): Mongo-backed job queue with lease + visibility timeout (WB-02)

CI / Check (pull_request) Successful in 5m49s

Details

CI / Detect Changes (pull_request) Has been skipped

Details

CI / Deploy Agent (pull_request) Has been skipped

Details

CI / Deploy Dashboard (pull_request) Has been skipped

Details

CI / Deploy Docs (pull_request) Has been skipped

Details

CI / Deploy MCP (pull_request) Has been skipped

Details

25f232774e

The control-plane pull queue behind the Werkbank runner flow (implements
sharang/werkbank#3). A JobQueue over a `werkbank_jobs` collection:

- enqueue — idempotent by job id (unique index; duplicate is a no-op)
- lease — atomic find-and-modify of the oldest queued job the runner can run,
  matched by executor and by labels (job labels must be a subset of the runner's,
  empty/absent matches any), returns the job + a lease token, bumps attempts
- heartbeat — extends the lease, flips leased→running, surfaces a cancel request;
  None means the lease was lost (token mismatch / already terminal)
- complete — records the terminal result, token-guarded and only from an active
  state, so it's idempotent
- cancel — queued→cancelled outright, in-flight flagged for the next heartbeat
- sweep_expired — the visibility timeout: expired leases go back to queued, or to
  expired once attempts hit max, so a crashed runner's job recovers

All transitions are single atomic Mongo updates guarded by the lease token, so two
runners can never both own a job. Every op takes an explicit `now` for
deterministic tests. Adds JobRecord/LeasedJob/HeartbeatAck to the contract (BSON
datetimes so range queries compare correctly) and the werkbank_jobs indexes.

Tests: 5 integration against a real Mongo (idempotent enqueue, executor+label
matching + FIFO, heartbeat/cancel, token-guarded idempotent complete, sweep
requeue→expire; skip cleanly with no Mongo) + 2 unit. clippy + fmt clean.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

sharang merged commit 633f945a1e into main

2026-07-17 09:15:24 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: sharang/compliance-scanner-agent#206

feat(werkbank): Mongo-backed job queue with lease + visibility timeout (WB-02) #206

JobQueue (over a werkbank_jobs collection)

Contract + schema

Tests

`JobQueue` (over a `werkbank_jobs` collection)