Module queue 

weave land --queue — a landing queue kept in the shared bare repository. Experimental: the protocol and its refs may change.

Many agents, one origin, one branch: every candidate is landed by exactly one process at a time, in submission order, so no push can race another.

Why refs and not a daemon

The bare origin is the one thing every agent container already shares, and git push --atomic with --force-with-lease on every ref is a compare-and-swap over several refs at once. A daemon would need an address every container can reach, a process someone keeps alive, and its own crash story; the refs need none of that and survive any process dying.

Protocol

Three append-only commit chains under refs/weave/<branch>/ (each commit’s tree is empty, its first parent the previous head, its message JSON). Only ref creations and fast-forwards are ever pushed, so an origin with receive.denyNonFastForwards and receive.denyDeletes works unchanged (its pre-receive hook must admit refs/weave/*).

• queue: one commit per submission. Its second parent is the candidate (so the candidate travels with it and stays reachable); the ticket number is the chain depth (0, 1, 2, …). Enqueue = fast-forward with a lease on the old head; losing the race means retrying on the new head.
• done: one commit per processed ticket, in ticket order. Its message is the result (landed / refused, reason, files, conflict regions, report); a landed result’s second parent is the commit published.
• lock: who lands. A commit whose holder is null means free. Acquire = append a commit naming yourself with a lease on the free head; the holder appends a renewal every ttl/3. A waiter that sees the same lock head unchanged for ttl by its own clock (skew-free) takes it over with a lease on that head.

Landing ticket n (the next after done’s head) is ONE atomic push: main (lease: the tip that was merged and checked), done (lease: its head) and a lock renewal (lease: the holder’s last lock head). A lander whose lock was taken over has a stale lock lease, so its push fails as a whole: main never moves except by the current holder, and only to a tree that crate::onto::prepare gated and verified against that exact tip.

A submitter enqueues, then waits for its ticket’s result in done. While waiting it takes the lock when it is free (or stale) and lands tickets in order up to its own, so the queue needs no process of its own and keeps moving while any submitter is alive. A ticket outlives its submitter.

Structs

QueueOptions

What --queue was asked to do.

TicketResult

The result of one ticket, as recorded in done.

Enums

QueueOutcome

How a --queue run ended.

Functions

submit

Submit HEAD to the queue and wait until it is landed or refused, landing other tickets ahead of it while holding the lock.