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, its id, and the name of the file that holds it. Why: Finishing needs the claim’s file name, not the id: the name carries the generation of the claim, so a settlement or a renewal reaches only the claim it was made for. The consumer needs the item.

Recovered

What: What a recovery pass did: how many claims it moved, and the items it gave up on. Why: An item that reaches failed through recovery was never settled by a handler, so nothing recorded a notice for it; the caller needs the items to tell the person.

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.

RECOVERING

Held by one instance that is returning an expired claim to pending; see requeue_with.

VERSION

The record format version.

WORK_DIRECTORY

Directory under the worktree’s own Git directory (WorkItem::git_dir) that holds the state directories.

Functions

claim_file_name

What: The name of the file that holds the claim of id of the generation token as of the reading stamp. Why: The generation is unique to one acquisition and the reading says when the holder last proved it was alive, so the name alone tells every other instance whose claim this is and whether it ran out, and a rename of exactly that name is the only way to take it: a holder that renews changes the name, so a take made from an older look finds nothing to take.

claim_next

What: Claim the oldest pending item by renaming it into claimed under a name that carries a fresh generation and the reading now. 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. The generation and the reading are in the name, so the claim is whole from the instant it exists; nothing is written to it.

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.

find_claim

The path of the file that holds the claim of id now, or nothing when it is not claimed or being recovered.

id_of_entry

What: The id an entry of claimed or recovering is the claim of: the part of its name before the generation. Why: A claim by an earlier release is named by the id alone, so a name with no separator is its own id.

next_claim_expiry

What: How long until the first claim that is still held runs out its lease, or nothing when no claim is held. Why: An instance that finds claims it may not take yet has nothing to wake it when they run out, so the service asks when to look again; without this, work whose holder died would wait for the next commit.

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.

renew_claim

What: Start the lease of the claim file name again at now, returning its new name; nothing when the claim is no longer in claimed under that name. Why: A holder that is still working must not look abandoned: every consumer of a directory that several consumers drain reads the reading in the name as the proof of life. The renewal is a rename of the exact name the holder last wrote, so a claim that was taken over, settled, or taken over and claimed again by someone else is not found and is never brought back or renewed on the other’s behalf; and an instance that looked at the old name and means to take it finds nothing.

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.

requeue_expired_reporting

requeue_expired that also gives the items it moved to failed for want of tries.

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. The rename names the claim’s generation, so a holder whose claim was taken over and claimed again by another settles nothing of the other’s.

settle_named

settle for the claim file name, whose id is the part of the name before the generation.

state_directory

The directory of one state.