Module work_item 

The durable work-item record for asynchronous work (review, push, maintenance) left for a resident consumer. What: The durable work-item record: a small file in the Git directory that says “this landed object needs this asynchronous work”, written by the wrapper and drained by a separate resident consumer. Why: A wrapper process exits when its command ends, and it may start no program, so work that must not delay a landing (the standards review, later auto-push and maintenance) is left as a record instead. The record is generic: a kind, the landed object and an id derived from both, so a retry cannot duplicate it. The design, its failure cases and the consumer contract are in doc/planning/cli-git-standards-review-port.md. Nothing calls this yet.

In TS you’d write (pseudocode):

await enqueue(workDir, { kind: 'review', oid, ... }); const item = await claimNext(workDir); await finish(workDir, item);

Structs

Claimed

What: A held item: the decoded record and its id. Why: Finishing needs only the id; the consumer needs the item.

WorkItem

What: One work item: what to do, to which landed object, and where. Why: The consumer needs only the object name and the places to find the repository; it reads the patch itself.

Enums

Enqueued

What: Whether an enqueue added the item or found it already known. Why: A landing that is replayed, or a daemon that restarts, enqueues again; the second time must change nothing.

WorkKind

What: The kind of work an item asks for. Why: One record format carries every asynchronous job; the kind picks the consumer’s handler.

Constants

CLAIMED

Held by one consumer, with a lease.

DONE

Finished.

FAILED

Given up after too many tries.

PENDING

The state directories, in the order an item moves through them.

VERSION

The record format version.

WORK_DIRECTORY

Directory under the common Git directory that holds the state directories.

Functions

claim_next

What: Claim the oldest pending item by renaming it into claimed, stamping the claim time as its lease start. A record that does not decode is moved to failed so it cannot block the queue. Why: A rename is atomic: of two consumers racing for one item, the loser sees the file gone and takes the next one.

claim_next_of

What: Claim the oldest pending item of the given kinds, leaving every other kind where it is. Why: Consumers of different kinds share one queue; the kind starts the file name, so a consumer never opens, moves or stamps an item that belongs to another.

enqueue

What: Write the item as a pending record, whole or absent, unless its id is already in any state. The producer never waits for a consumer and never reads anything back. Why: The id is the idempotency key; the exclusive publish makes two racing producers agree on one winner.

oldest_pending_age

What: How long the oldest pending item has waited, or None when nothing is pending. Why: The wrapper’s one-line notice that no consumer is draining the queue is this age past a bound; a process id in a file would be meaningless across process-id namespaces.

requeue_claimed

What: Return every claim to pending with one more try, or to failed at max_tries, whatever its age. Returns how many were moved. Why: A consumer that starts holds no claim yet, and the manager runs one consumer at a time, so a claim it finds was left by a consumer that died or was replaced; waiting out the lease would strand the work for as long as the lease lasts.

requeue_expired

What: Return claims whose lease ran out to pending with one more try, or to failed at max_tries. Returns how many were moved. Why: This is how a consumer killed at any instruction is noticed when nothing says its successor started: by its lease, never by a process id.

settle

What: Move a claimed item to done (or to failed), after the consumer’s result is durable. Why: A crash before this rename leaves the item claimed, and its lease runs out; the work is then done again, so a handler must tolerate a repeat.

state_directory

The directory of one state.