Module queue 

Per-repo, priority-ordered execution queue (design: docs/backlog-and-slack.md §3).

Approval enqueues a mission rather than starting it. Entries live as one JSON file each under .kranz/queue/, named <priority>-<paddedSeq>-<missionId>.json so plain lexicographic filename order equals (priority, insertion order). A monotonic counter file (.seq) assigns the sequence number.

Per-repo serialization is mandatory: missions share the working tree, so at most one may run at a time in a repo. Queue dispatchers acquire a repo-wide busy guard as part of claiming work, and is_repo_busy reports that guard (falling back to legacy live events.jsonl.lock detection).

Structs

Claim

A claimed queue entry: the entry file was atomically RENAMED to <name>.json.claimed.<pid>, so no sibling dispatcher can double-run it, and a crash before completion leaves a recoverable file instead of dropped work. Call finish_claim when the mission reached a terminal state (any outcome), or release_claim to put the entry back.

EnqueueSource

QueueEntry

One queued mission.

RepoBusyHold

Public RAII hold on the repo-wide busy lock — same underlying guard the queue claim path uses. Drop (or end of scope) releases the lock so a sibling dispatcher or hosted start can proceed.

Enums

ClaimFront

Result of atomically taking work with the repo-wide busy guard.

Constants

ENQUEUE_SOURCE_FILE

Durable producer binding written before an externally-owned queue entry becomes visible. Unlike the queue entry itself, this survives any valid dispatcher consuming the entry, so the producer can reconcile the mission’s terminal state afterward.

ENQUEUE_SOURCE_RETURNED_FILE

Archived binding after the external producer has confirmed its return transition. Kept beside the mission for audit, outside active scans.

Functions

acquire_repo_busy

Acquire the repo-wide busy lock for mission_id. Returns EngineError::LockHeld when another live holder already owns it.

claim_front

Atomically claim the front entry, if any. A lost rename race (a sibling claimed first) retries with the next front.

claim_front_when_repo_free

Claim the front queue entry only if this repo is not already running a mission. The queue claim and repo busy guard travel together in Claim, so the guard stays held until finish_claim or release_claim consumes it after the injected mission runner returns.

contains

Whether mission_id is currently queued.

enqueue

Enqueue a mission. The entry’s seq is assigned here from the monotonic counter (any incoming seq is overwritten). Write is atomic (temp + rename). A no-op if the mission is already queued.

finish_claim

The mission ran to a terminal state (any outcome): retire the claim.

is_repo_busy

The mission id currently RUNNING in this repo, if any: detected by any repo-wide busy guard, falling back to any legacy .kranz/missions/*/events.jsonl.lock whose recorded pid is still alive.

list

All queued entries, sorted by (priority, seq) (== filename order).

peek

The front of the queue (highest priority, then earliest insertion), if any.

queue_dir

The .kranz/queue/ directory for a repo.

read_enqueue_source

Read a live external producer binding. Malformed or absent files are not ownership evidence and return None.

recover_dead_claims

Recover claims left by dead dispatchers. A *.claimed.<pid>[.<token>] file is renamed back to its entry name when its claimant is provably gone — or, when liveness cannot be determined, when the file is over an hour old (the pid-REUSE backstop).

release_claim

The mission could NOT be run (start failure, lock held, config error): put the entry back so the work is not lost.

remove

Remove the entry for mission_id. Returns true if something was removed.

remove_enqueue_source

Roll back a source binding when the queue write itself fails. Once enqueue succeeds, producer-owned code retires the binding only after its external return is confirmed.

write_enqueue_source

Persist an external producer binding atomically. Callers must do this before enqueue so even a sibling dispatcher that claims immediately cannot erase the only mission-to-producer join.