Module queue_item_lifecycle 

Pure queue-item lifecycle lattice shared by CRDT convergence (agent-doc-core) and the orchestration-layer queue state machine (agent_doc_orchestration::queue_item_state_machine, #queuestatemachine1).

Why this lives in core (#queuestatemachine2 / #qheadresidue)

The orchestration queue_item_state_machine models a queue head’s lifecycle as a total order whose transition is the join (max) over lifecycle rank, so a stale re-emit “cannot resurrect the item as a fresh queue head.” That guarantee only held in isolation: the actual CRDT queue convergence (crate::crdt::merge_by_component) bypassed it and ran a blind Yrs leaf merge per item, which let a stale un-strike from the persisted .yrs base win and resurrect a struck head every cycle (the live churn).

agent-doc-core is the lower crate (orchestration depends on it, not the reverse), so the pure lattice the convergence needs to consult lives here. The orchestration queue_item_state_machine re-exports QueueItemLifecycle and keeps its richer event-driven QueueItemState machine on top of it, so there is a single authoritative lifecycle model rather than two diverging copies.

The structural guarantee, applied to convergence

A queue item’s visible lifecycle state is recoverable from its rendered text: a struck (~~…~~) item is answered-and-retired; an un-struck item is live. The lattice orders Live < Struck. Reconciling a matched item across the three merge sides is the join of their visible states: if any authoritative side says Struck, a stale Live contribution is a no-op and the item stays struck. Resurrection becomes structurally impossible instead of patched after the fact.

Enums

QueueItemLifecycle

Visible lifecycle state of a single rendered queue item, in ascending lawful order. This is the coarse lattice the CRDT convergence joins over; the orchestration QueueItemState is a finer-grained refinement that maps onto it.