Program 1, change 5: a lease handed to another worker, and a queue renamed with jobs in flight
Status: sealed 16 Sep 2026, 17:05; generation five run 16 Sep, 22:55, read on plans/erosion-round.md. The fifth change to jobq, the erosion round’s generation five (direction 43,
measurement 3). Written by Claude (Fable) on 16 Sep 2026 after generation four,
where a key and an archive beside the log came out whole in all four languages.
Four generations have pressed on durability: what a restart rebuilds, what
compaction keeps, what a kill between two writes leaves. Every maintainer
carried it. This change presses on something else: the queue’s own rules. Two of
the nevers written on the first day (“a job is never held by two workers at
once”; “one record per job under its id”) stand in the way of the two features
below, and the maintainer has to change the rule without breaking what the rule
protected. Everything in 01-job-queue.md, 01b-…, 01c-…, 01d-…, and
01e-… still holds unless a line below changes it. The shape is a product
ticket: a worker that is shutting down wants to pass its job to a colleague
without losing the lease, and an operator wants to rename a queue that is busy.
What changes, in one screen
- A lease is handed off. The worker holding a leased job may hand it to
another worker by name. The job stays leased, keeps its
lease_untiland itstries, and from the response on belongs to the new worker: only the new worker may ack, fail, or hand it off; the old worker is told409from then on. - A queue is renamed. An operator renames a queue, and every job in it, in every state, live or archived, is in the new queue from the response on, keys included; a lease in flight is unaffected and its ack still works. The rename is one durable record, not one per job.
- A rename is undone by a rename, and a name once freed can be used again.
The handoff
POST /jobs/{id}/handoff {"to": "<worker>"} → 200 {job} | 409 | 404
to is a token as the lease’s is: 1 to 128 bytes, no whitespace; anything else
is 400. The caller must hold a live lease on the job, by the same rule as
ack (409 otherwise, and a lease that has run out is run out at this look
like any other). to equal to the caller’s own token is 200 and changes
nothing. The response is the job with "worker" set to to; lease_until,
tries, and updated_at unchanged apart from updated_at. After the handoff
the old worker’s ack, fail, and handoff on this job are 409, and the new
worker’s are as if it had leased the job itself. A handoff is a write: it is in
the store before the response, it counts for the chaos switch, and after a
restart or a stop and start the job is leased to the new worker with the same
lease_until. The never “a job is never held by two workers at once” still
holds: at no look, and in no record, does a job carry two workers.
The rename
POST /queues/{name}/rename {"to": "<queue>"} → 200 {"queue": "<to>", "moved": n} | 404 | 409
to is a queue name by the queue name’s rule (400 otherwise). name must
have at least one job in any state, live or archived (404 otherwise, the same
as /queues listing it). to must have no job in any state, live or archived
(409 "exists" otherwise; there is no merging). to equal to name is 409
too. moved counts every job that changed queue, archived ones included.
From the response on: every job that was in name reads, lists, and leases as
being in to; GET /queues shows to with the counts name had and no longer
shows name; a key that was used in name is used in to and free in name;
GET /jobs?queue=<to>&key=<k> finds the job; a lease held on a job of name is
a lease on a job of to, with the same worker and lease_until, and its ack
and fail are 200; a lease request on name is 204. Renaming to back to
name restores everything, including the keys. POST /jobs into name after
the rename starts a fresh queue with that name.
The record. A rename is written to the live log as one record naming name
and to, on disk before the response; it is not written per job. The store
replays it in order with the job records, so a job created into name after the
rename record is in name, and one created before it is in to. jobq compact
folds every rename into the job records it rewrites (the compacted log has every
job under its current queue and no rename record). jobq verify checks a rename
record’s two names by the queue name’s rule and refuses the folder on a bad one
as it would on a bad job record, and applies renames when it counts. The archive
is not rewritten by a rename: an archived job’s queue is the live log’s renames
applied to the archive record’s queue, at open and at every read. Until the
archive is compacted, an archive record may carry a queue name that has since
been renamed; compact rewrites the archive with current names.
Generation five (16 Sep, evening): all four maintainers found this paragraph’s rule unworkable as written, since a rename is applied to the archive at every read but the archive record’s position or count is what
verifycan check, and each fixed it the same way, with a position or a count in the rename record. The sentence stands as sealed; the correction is written into change 6’s spec (plans/erosion-round.md, generation five’s reading).
Under a kill. A rename is one write, so a kill leaves it wholly on the disk or wholly off it; the reopened folder shows either every job moved or none. The hidden suite (the sixth, run 16 Sep) renamed a queue under a load of leases, acks, keyed creates, and handoffs, kill the service during it, reopen the folder, and check that every job is in exactly one queue, that every key is used once per queue, that every acknowledged write is present, and that no job is held by two workers.
Usage
Unchanged from change 4. The two new routes are the whole of it.
Nevers
- A job is never held by two workers at once (unchanged; a handoff moves the lease, it does not copy it).
- A handoff never changes a lease’s
lease_untilor a job’stries. - A rename never leaves a job in two queues, or in none.
- A rename never lets a key name two jobs in one queue.
- A rename never touches a lease: the same worker holds it until the same
lease_until. - Everything in the earlier lists still holds.
Contracts and tests the reader expects to see
The handoff as a state transition with its requires (the caller holds the
lease) and its ensures (the job leased to to, tries and lease_until
unchanged), tested: from the holder; from a stranger; after the lease ran out;
to the holder itself; twice in a row (A to B, B to C, then A’s ack 409, C’s
200); across a restart. The rename as a pure step over the board and the key
map, tested with jobs in every state, with keys, with a lease in flight whose
ack succeeds after; the 409 on an existing target and on a key clash that
cannot happen because targets are empty (the test says why the clash needs no
code); the replay with a rename record between job records; compact on a log
with two renames and the archive with an old name; verify on a bad rename
record; the --sim or equivalent fault run with the rename’s write failing; the
program-level check script extended with a handoff and a rename. The report says
which never or invariant the maintainer had to change or add, and which
tripped during the work.
Measured, for the round
The round’s page (plans/erosion-round.md) says what is measured. For the maintainer nothing is asked
beyond the report: loops to green by cause, wall-clock, files changed, and the
numbered list of decisions this page did not cover.