# Eve SOTA queue semantics — `eve.queue-semantics.v1` - **Task:** 2.2 - **Evaluated:** 2026-09-04 - **Decision:** queue-semantics-enforced - **ADR gate:** `queue-dependency-and-fencing-contract` (docs/adr/ADR-0076-eve-governed-delivery-lifecycle.md) - **Record digest:** `4b58bf36e12425f7f4b554b043e43917715aebcfa22e507d7deb090f5583fb55` ## The rule Queue admission is one door. Every acquisition passes TTL, quarantine, retry budget, concurrency (one locally; N only under a human-accepted spend decision), and dependency readiness before any state is written, and mints the next monotonic fencing token. Every later write by that holder presents the token or is refused. Keyed requests replay exactly once. Orphan classes recover separately. Rejection and unpark are human authority acts. Every counter in this record is folded from the append-only ledger by one step function that the live projection and replayLedger both call; the queue_state column is a cache of that fold, not a second truth. ## The eleven semantics, and where each is enforced | # | Semantic | Requirement | Enforced in | Refusals | | --: | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------ | | 1 | `local-concurrency-one` | Local execution admits exactly one live lease at a time; the limit is not configurable downward or upward by a caller. | `work-queue.ts` | `concurrency_exhausted` | | 2 | `cloud-concurrency-after-spend-approval` | Cloud concurrency N is admitted only when the named decision is accepted BY A HUMAN; an unapproved cloud policy admits nothing at all rather than falling back to a smaller budget. | `work-queue.ts` | `spend_not_approved` | | 3 | `priority-fairness-starvation` | Ready items are ordered by priority aged one class per aging interval, giving an exact starvation ceiling of baseRank x agingInterval before any item competes with a fresh high-priority arrival. | `work-queue.ts` | _none_ | | 4 | `lease-ttl-and-renewal` | A lease TTL must fall inside the policy window; only the live holder may renew, and renewals cannot carry one acquisition past the maximum lease age. | `work-queue.ts`, `intent-store.ts` | `lease_ttl_out_of_range`, `lease_age_exceeded`, `not_lease_holder` | | 5 | `monotonic-fencing-token` | Each acquisition mints a strictly increasing per-item token folded from the ledger; a holder write that presents an absent, older, or newer token is refused, so an agent cannot supersede itself unnoticed. | `intent-store.ts` | `stale_fence` | | 6 | `idempotency-key` | A keyed request that repeats identically returns the prior outcome and appends no event; the same key with different arguments is refused rather than answered with the old result. | `intent-store.ts` | `idempotency_conflict` | | 7 | `retry-budget` | The retry budget is spent in acquisitions, so an agent that crashes without reporting still spends one; an item past the budget is refused. | `work-queue.ts` | `retry_budget_exhausted` | | 8 | `poison-item-quarantine` | An item whose budget is spent is parked with a structured quarantine record instead of recycling through the queue; only a human unpark returns it, and the spent attempt history is not erased. | `work-queue.ts`, `intent-store.ts` | `quarantined` | | 9 | `dependency-readiness` | Every declared dependency must have reached verified, or be waived by a decision a human accepted; unknown ids and cycles fail closed. | `work-queue.ts` | `dependency_not_ready`, `unknown_dependency`, `dependency_cycle` | | 10 | `orphan-recovery` | Expired leases, rows holding no lease, and holds whose token the ledger superseded are three distinct evented recoveries, each guarded by the exact lease observed. | `work-queue.ts` | _none_ | | 11 | `terminal-state-ownership` | Rejection and unpark are human authority acts; verified stays capability-gated rather than actor-gated, so no actor type can name its way into it. | `intent-store.ts` | `terminal_state_not_owned` | ## Local policy, read from the contract module | Setting | Value | | --------------------------- | ----: | | Concurrent leases | 1 | | Lease TTL floor (s) | 60 | | Lease TTL ceiling (s) | 86400 | | Maximum acquisition age (s) | 14400 | | Attempts before quarantine | 3 | | Fairness aging interval (s) | 3600 | The starvation ceiling follows from the aging rule: an item at base rank `r` reaches rank 0 after `r x 3600` seconds, so nothing waits more than 10800 seconds before it competes on equal terms with a freshly created high-priority item. ## Refusal vocabulary All 15 codes are produced by the contract and asserted by a spec; unreachable: 0, unasserted: 0. - `fleet_halted` - `not_acquirable` - `concurrency_exhausted` - `spend_not_approved` - `dependency_not_ready` - `unknown_dependency` - `dependency_cycle` - `retry_budget_exhausted` - `quarantined` - `stale_fence` - `idempotency_conflict` - `lease_ttl_out_of_range` - `lease_age_exceeded` - `not_lease_holder` - `terminal_state_not_owned` ## Transport surface - BFF route accepts a fencing token: true - BFF route accepts an idempotency key: true - BFF route maps queue refusals to distinct statuses: true - MCP tool exposes the fencing token: true - MCP tool exposes the idempotency key: true - Projection column: `work_item.queue_state`, constraint `work_item_queue_state_shape` ## Honest limits - This record closes task 2.2 only. It does not build the drain (2.3), typed triage (2.4), the operator read model (2.5), execution isolation (2.6), the orchestrator model and parity proof (2.7), or any live backlog or soak evidence (2.8). - Enforcement is proved at the pure decision layer and at real local PostgreSQL. No live coding agent, MCP session, cloud fleet, or spend has been exercised under this contract. - The cloud concurrency path is implemented and tested against decision records in the local database; no cloud execution has been approved or performed, and the maximum authorised concurrency is a code-level ceiling rather than a ratified operator decision. - Fencing exempts leases written before this contract, which carry no token. Those leases remain guarded only by holder identity and expiry until they end. - Dependency readiness is enforced over dependencies DECLARED on the work item. The durable dependency-DAG entity ADR-0076 stage 3 requires remains owned by task 11.2; this contract refuses unknown ids and cycles but cannot prove a plan declared the right edges. - The starvation bound is a property of the aging rule over a snapshot, not a measured throughput result; task 2.8 owns real backlog behaviour.