{"id":"durable-actions-idempotency","name":"Durable actions and the ambiguous timeout","shortName":"Durable actions and the ambiguous timeout","role":"Persist intent, execute with idempotency key, store receipt and recover without duplicate business effects.","description":"A write can commit even when its response never reaches the caller. Retrying blindly then risks creating a second external effect; refusing every retry can leave a valid task unfinished. An idempotency key names one logical action, while a payload fingerprint records exactly which action that key refers to. The service stores an effect and its receipt together at its own boundary. A matching retry returns the original receipt; a changed payload under that key must not silently reuse or replace it. A workflow journal records intent before service and observations afterward. Those records can lag the external effect. The incident experience deliberately separates local journal and environment storage so an interrupted result write leaves a real reservation to recover. This is different from restoring neural weights or replaying lost arithmetic: an external reservation is already part of the world.","mechanism":["Persist the approved action intent before starting the service that can mutate inventory.","The service validates the key and payload, commits one reservation and stores its original receipt.","If the response is lost, the caller records uncertainty rather than success or proof that nothing happened.","Receipt lookup or an identical idempotent retry recovers the outcome; conflicting arguments fail without another effect."],"learningObjective":"Explain the caller’s uncertainty and prove that recovery preserves one logical effect after a commit-before-response failure.","engineeringExample":"FAN-7 begins with four FILTER-A units. The reservation for quantity two commits, leaving two units and receipt K. The response is lost. A repeat request carrying K and the same payload returns the original reservation: stock stays at two. A request carrying K but quantity one conflicts with its stored fingerprint and changes nothing. If result journaling itself fails, reload retains the committed environment and the pending intent; recovery reconciles that exact receipt before continuing to the work order.","misconception":"A timeout is neither proof of nonexecution nor permission to issue a new logical action.","check":{"question":"After the reservation committed but its reply was lost, what should the same-key retry do?","options":["Reserve two more units","Return the original receipt without changing stock","Erase the first reservation"],"answer":1,"explanation":"The service recognizes the same logical action and returns its already committed outcome."},"checks":[],"prerequisites":["event-queues-delivery"],"related":["tool-loop","evaluation"],"specs":[{"label":"Mechanism boundary","value":"Did a timed-out write happen?","context":"The key and payload are unchanged, receipt retention covers the retry, and the service atomically commits the effect and receipt. This is an effect guarantee under those assumptions, not an exactly-once network-delivery claim."},{"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":"Persist the approved action intent before starting the service that can mutate inventory."},{"name":"Checked outcome","direction":"out","signal":"Explain the caller’s uncertainty and prove that recovery preserves one logical effect after a commit-before-response failure."}],"tradeoff":"Idempotency requires durable service-side identity and payload matching; a client-side retry counter alone cannot supply that guarantee.","whyAI":"Agents and workflows can be restarted, but durable side effects need an explicit recovery contract.","sourceIds":["automation-temporal-activities","automation-temporal-history","automation-langgraph-persistence"],"sources":[{"title":"Temporal Activities","url":"https://docs.temporal.io/activities"},{"title":"Temporal Workflow Execution","url":"https://docs.temporal.io/workflow-execution"},{"title":"LangGraph persistence","url":"https://docs.langchain.com/oss/python/langgraph/persistence"}],"science":[{"title":"Durable actions and the ambiguous timeout · explicit relationship","equation":"Applying the same keyed action with the same payload to world state twice has the same effect as applying it once.","explanation":"FAN-7 begins with four FILTER-A units. The reservation for quantity two commits, leaving two units and receipt K. The response is lost. A repeat request carrying K and the same payload returns the original reservation: stock stays at two. A request carrying K but quantity one conflicts with its stored fingerprint and changes nothing. If result journaling itself fails, reload retains the committed environment and the pending intent; recovery reconciles that exact receipt before continuing to the work order.","assumptions":"The key and payload are unchanged, receipt retention covers the retry, and the service atomically commits the effect and receipt. This is an effect guarantee under those assumptions, not an exactly-once network-delivery claim."}],"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. The key and payload are unchanged, receipt retention covers the retry, and the service atomically commits the effect and receipt. This is an effect guarantee under those assumptions, not an exactly-once network-delivery claim.","level":"software","branch":"From request to durable action","subbranch":"Durable actions and the ambiguous timeout","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":{"stockBefore":4,"quantity":2,"stockAfterFirst":2,"stockAfterRetry":2}}