{
  "schemaVersion": 1,
  "id": "atlas-lesson-durable-actions-idempotency",
  "title": "Durable actions and the ambiguous timeout",
  "category": "learning",
  "format": "Atlas lesson",
  "description": "Persist intent, execute with idempotency key, store receipt and recover without duplicate business effects.",
  "canonicalUrl": "https://semiaifoundry.com/learn/atlas/durable-actions-idempotency/",
  "publishedDate": null,
  "revisionDate": "2026-10-07",
  "author": null,
  "topic": "From request to durable action",
  "series": null,
  "license": null,
  "rightsUrl": "https://semiaifoundry.com/ai-atlas/licenses.html",
  "version": "1.3.0",
  "status": "Published educational lesson",
  "evidenceScope": "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.",
  "contentCoverage": "published-lesson",
  "artifactUrl": "https://semiaifoundry.com/ai-atlas/lesson-data/durable-actions-idempotency-0913e642cc5c0015.json",
  "interactiveUrl": "https://semiaifoundry.com/ai-atlas/#durable-actions-idempotency",
  "related": [],
  "supersedes": [],
  "supersededBy": [],
  "contentHash": "0798117f7c94bcae8ec1a5d38eb9650bf2681280869a16b4264beff7e198282d",
  "contentLength": 7079,
  "jsonUrl": "https://semiaifoundry.com/agents/publications/atlas-lesson-durable-actions-idempotency.json",
  "markdownUrl": "https://semiaifoundry.com/agents/publications/atlas-lesson-durable-actions-idempotency.md",
  "sections": [
    {
      "id": "section-1",
      "title": "Durable actions and the ambiguous timeout",
      "start": 47,
      "end": 506
    },
    {
      "id": "section-2",
      "title": "The mechanism",
      "start": 506,
      "end": 1870
    },
    {
      "id": "section-3",
      "title": "Science and assumptions",
      "start": 1870,
      "end": 1898
    },
    {
      "id": "section-4",
      "title": "Durable actions and the ambiguous timeout · explicit relationship",
      "start": 1898,
      "end": 3147
    },
    {
      "id": "section-5",
      "title": "Engineering example",
      "start": 3147,
      "end": 3684
    },
    {
      "id": "section-6",
      "title": "Distinctions and tradeoffs",
      "start": 3684,
      "end": 4044
    },
    {
      "id": "section-7",
      "title": "Specifications and interfaces",
      "start": 4044,
      "end": 4659
    },
    {
      "id": "section-8",
      "title": "Interfaces",
      "start": 4659,
      "end": 4949
    },
    {
      "id": "section-9",
      "title": "Check your understanding",
      "start": 4949,
      "end": 4978
    },
    {
      "id": "section-10",
      "title": "After the reservation committed but its reply was lost, what should the same-key retry do?",
      "start": 4978,
      "end": 5354
    },
    {
      "id": "section-11",
      "title": "Evidence and scope",
      "start": 5354,
      "end": 6298
    },
    {
      "id": "section-12",
      "title": "Sources",
      "start": 6298,
      "end": 6748
    },
    {
      "id": "section-13",
      "title": "Continue exploring",
      "start": 6748,
      "end": 6771
    },
    {
      "id": "section-14",
      "title": "Foundations",
      "start": 6771,
      "end": 6889
    },
    {
      "id": "section-15",
      "title": "Related lessons",
      "start": 6889,
      "end": 7079
    }
  ],
  "citations": [
    {
      "title": "Explore in Atlas",
      "url": "https://semiaifoundry.com/ai-atlas/#durable-actions-idempotency"
    },
    {
      "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"
    },
    {
      "title": "Published lesson data",
      "url": "https://semiaifoundry.com/ai-atlas/lesson-data/durable-actions-idempotency-0913e642cc5c0015.json"
    },
    {
      "title": "Atlas releases and licensing",
      "url": "https://semiaifoundry.com/ai-atlas/licenses.html"
    },
    {
      "title": "Events, queues and backpressure",
      "url": "https://semiaifoundry.com/learn/atlas/event-queues-delivery/"
    },
    {
      "title": "Tools, memory & agent loop",
      "url": "https://semiaifoundry.com/learn/atlas/tool-loop/"
    },
    {
      "title": "Evaluation & the AGI frontier",
      "url": "https://semiaifoundry.com/learn/atlas/evaluation/"
    }
  ],
  "recordHash": "5e95f60bb65b13ab04dea0d8ac5d0a6e457e7c6035ff802f0ad181fd70013d3f",
  "contentFormat": "text/markdown",
  "content": "From request to durable action · Atlas v1.3.0\n\n# Durable actions and the ambiguous timeout\n\nPersist intent, execute with idempotency key, store receipt and recover without duplicate business effects.\n\n[Explore in Atlas](https://semiaifoundry.com/ai-atlas/#durable-actions-idempotency)Logical state, task evidence and declared units; no physical assembly scale\n\nLearning objectiveExplain the caller’s uncertainty and prove that recovery preserves one logical effect after a commit-before-response failure.\n\n## The mechanism\n\nA 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.\n\n1.  Persist the approved action intent before starting the service that can mutate inventory.\n2.  The service validates the key and payload, commits one reservation and stores its original receipt.\n3.  If the response is lost, the caller records uncertainty rather than success or proof that nothing happened.\n4.  Receipt lookup or an identical idempotent retry recovers the outcome; conflicting arguments fail without another effect.\n\n## Science and assumptions\n\n### Durable actions and the ambiguous timeout · explicit relationship\n\n$$\nF_{k,p}\\!\\left(F_{k,p}(W)\\right)=F_{k,p}(W)\n$$\n\nApplying the same keyed action with the same payload to world state twice has the same effect as applying it once.\n\nSymbols and units\n\nW\n\nExternal environment, including the receipt ledger\n\nstate object\n\nk\n\nStable logical action key\n\nidentifier\n\np\n\nExact action payload bound to the key\n\ndata object\n\nFₖ,ₚ\n\nService transition with an atomic keyed receipt\n\nstate transition\n\nFAN-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.\n\nAssumptions 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.\n\n## Engineering example\n\nFAN-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.\n\n## Distinctions and tradeoffs\n\nA timeout is neither proof of nonexecution nor permission to issue a new logical action.\n\nIdempotency requires durable service-side identity and payload matching; a client-side retry counter alone cannot supply that guarantee.\n\nAgents and workflows can be restarted, but durable side effects need an explicit recovery contract.\n\n## Specifications and interfaces\n\nMechanism boundary\n\nDid a timed-out write happen?\n\nThe 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.\n\nEvidence type\n\nAuthored worked example\n\nThe 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.\n\n### Interfaces\n\nDeclared input and state Input\n\nPersist the approved action intent before starting the service that can mutate inventory.\n\nChecked outcome Output\n\nExplain the caller’s uncertainty and prove that recovery preserves one logical effect after a commit-before-response failure.\n\n## Check your understanding\n\n### After the reservation committed but its reply was lost, what should the same-key retry do?\n\n1.  Reserve two more units\n2.  Return the original receipt without changing stock\n3.  Erase the first reservation\n\nAnswer and reasoning\n\nReturn the original receipt without changing stock\n\nThe service recognizes the same logical action and returns its already committed outcome.\n\n## Evidence and scope\n\nThe 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.\n\nThe 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.\n\n## Sources\n\n-   [Temporal Activities](https://docs.temporal.io/activities)\n-   [Temporal Workflow Execution](https://docs.temporal.io/workflow-execution)\n-   [LangGraph persistence](https://docs.langchain.com/oss/python/langgraph/persistence)\n\n[Published lesson data](https://semiaifoundry.com/ai-atlas/lesson-data/durable-actions-idempotency-0913e642cc5c0015.json) · [Atlas releases and licensing](https://semiaifoundry.com/ai-atlas/licenses.html)\n\n## Continue exploring\n\n### Foundations\n\n-   [Events, queues and backpressure](https://semiaifoundry.com/learn/atlas/event-queues-delivery/)\n\n### Related lessons\n\n-   [Tools, memory & agent loop](https://semiaifoundry.com/learn/atlas/tool-loop/)\n-   [Evaluation & the AGI frontier](https://semiaifoundry.com/learn/atlas/evaluation/)"
}