{"id":"event-queues-delivery","name":"Events, queues and backpressure","shortName":"Events, queues and backpressure","role":"Distinguish event occurrence, delivery, acknowledgement, deduplication, retries and admission.","description":"An event describes something that occurred; a delivery is one attempt to bring that event to a consumer. Networks, acknowledgements and worker failures can cause repeated or delayed deliveries. A queue therefore holds deliveries, while the consumer may track stable business event identities. Admission moves a delivery into service; deduplication can remove a repeated identity without repeating its effects. Queue length alone says nothing about unique useful work. A retry policy must also distinguish a request that never started from one whose acknowledgement was lost. In the incident experience two simultaneous deliveries name the same incident. One worker handles it, then acknowledges the remaining duplicate without another reservation. This is a bounded single-consumer example; it does not implement a general distributed queue or prove exactly-once delivery.","mechanism":["A stable event identity accompanies each delivery, separately from its arrival attempt.","The queue balance records arrivals, admissions into service and discarded duplicates at one declared boundary.","The consumer checks whether a delivery belongs to an already handled incident before beginning another workflow.","A durable effect still needs its own idempotency protection because a consumer may fail after service starts."],"learningObjective":"Reconcile arrivals, admissions and duplicate removals without confusing deliveries with distinct business tasks.","engineeringExample":"Start with an empty queue and deliver incident-017 twice. The queue contains two deliveries. Admission removes one, leaving one waiting while the worker makes four normal tool calls. After completion, deduplication removes the second delivery, so the queue returns to zero. Exactly one reservation and one work order exist. Two arrivals minus one admission minus one duplicate removal equals zero queued deliveries; counting deliveries as two successful incidents would overstate useful work.","misconception":"An acknowledgement retry does not necessarily represent a new task.","check":{"question":"Two copies of the same incident arrive; one is admitted and one is deduplicated. How many distinct incidents were executed?","options":["Two","One","Zero because a duplicate is an error"],"answer":1,"explanation":"The stable incident identity is the same on both deliveries; only one workflow executes."},"checks":[],"prerequisites":["workflow-graphs-state"],"related":["tool-loop","evaluation"],"specs":[{"label":"Mechanism boundary","value":"Why does one event sometimes arrive twice?","context":"Counts share one queue boundary. Admissions and duplicate removals cannot exceed available queued deliveries. Business effects are counted separately."},{"label":"Evidence type","value":"Authored worked example","context":"The durable incident experience executes typed fixture tools, authority checks, exact review, receipts and independent final-state checks. Its policies are authored code and its storage boundary is local; it is not a real model or production workflow platform."}],"interfaces":[{"name":"Declared input and state","direction":"in","signal":"A stable event identity accompanies each delivery, separately from its arrival attempt."},{"name":"Checked outcome","direction":"out","signal":"Reconcile arrivals, admissions and duplicate removals without confusing deliveries with distinct business tasks."}],"tradeoff":"Retaining deduplication identity uses state and needs an explicit retention scope; removing it too soon can permit old deliveries to repeat work.","whyAI":"Webhook-driven and tool-driven AI services face the same event-delivery ambiguity as other asynchronous systems.","sourceIds":["automation-temporal-activities","automation-temporal-history"],"sources":[{"title":"Temporal Activities","url":"https://docs.temporal.io/activities"},{"title":"Temporal Workflow Execution","url":"https://docs.temporal.io/workflow-execution"}],"science":[{"title":"Events, queues and backpressure · explicit relationship","equation":"Queued deliveries equal the previous queue plus arrivals, minus admissions into service and duplicate removals.","explanation":"Start with an empty queue and deliver incident-017 twice. The queue contains two deliveries. Admission removes one, leaving one waiting while the worker makes four normal tool calls. After completion, deduplication removes the second delivery, so the queue returns to zero. Exactly one reservation and one work order exist. Two arrivals minus one admission minus one duplicate removal equals zero queued deliveries; counting deliveries as two successful incidents would overstate useful work.","assumptions":"Counts share one queue boundary. Admissions and duplicate removals cannot exceed available queued deliveries. Business effects are counted separately."}],"evidenceNotes":"The durable incident experience executes typed fixture tools, authority checks, exact review, receipts and independent final-state checks. Its policies are authored code and its storage boundary is local; it is not a real model or production workflow platform. The quantities and fixtures are authored. Source scope is recorded in the automation learning review manifest; no source benchmark or private system behavior is claimed. Counts share one queue boundary. Admissions and duplicate removals cannot exceed available queued deliveries. Business effects are counted separately.","level":"software","branch":"From request to durable action","subbranch":"Events, queues and backpressure","scale":"Logical state, task evidence and declared units; no physical assembly scale","kind":"system","workstream":"W11","visualFamily":"software-flow","labId":"library","labScope":"The durable incident experience executes typed fixture tools, authority checks, exact review, receipts and independent final-state checks. Its policies are authored code and its storage boundary is local; it is not a real model or production workflow platform.","history":[],"workedTrace":{"initial":0,"arrivals":2,"admitted":1,"duplicatesRemoved":1,"final":0}}