Disciplines · Audits

Eve SOTA queue semantics — eve.queue-semantics.v1

Queue admission is one door.

6sections4 minread
Markdown source
On this page
  • 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.