{
  "schemaVersion": 1,
  "title": "Revision-safe document replacement",
  "blocks": [
    {
      "id": "process-intro",
      "type": "markdown",
      "markdown": "## Inputs and revision\n\nThis teaching model replaces a complete document without overwriting a newer update.\nRead retrieves the stored document and its revision, a version number.\nEdit prepares a complete replacement using that revision as expectedRevision.\nThe diagrams follow valid input; schema and policy errors are rejected before this write path and leave storage unchanged.\nLet $r$ be the stored revision; an accepted replacement increments it:\n\n$$\nr_{next} = r + 1\n$$\n\n```typescript\nconst update = {\n  documentId: \"4e7efb70-6686-4f94-aa51-f97d40abb677\",\n  expectedRevision: 3,\n  document: completeDocument,\n};\n```"
    },
    {
      "id": "process-deck",
      "type": "diagram-deck",
      "title": "Replacement path",
      "slides": [
        {
          "id": "process-overview",
          "title": "Replacement and retry",
          "mermaid": "flowchart TD\n  Read[\"Read\"] --> Edit[\"Edit\"]\n  Edit --> Write[\"Write\"]\n  Write -->|saved| Result[\"Saved\"]\n  Write -->|stale| Conflict[\"No write\"]\n  Conflict -->|refresh| Read",
          "explanationMarkdown": "Read supplies content and revision; Edit reapplies the intended change and sends a complete replacement to Write.\nWrite either persists the replacement and returns Saved, or returns a conflict with No write.\nThe conflict loop returns through both Read and Edit so unrelated updates are retained; it is not a blind retry."
        },
        {
          "id": "process-processing",
          "title": "Serialized write",
          "mermaid": "flowchart TD\n  Expected[\"Expected rev\"] --> Compare{\"Match?\"}\n  Current[\"Stored rev\"] --> Compare\n  Compare -->|Yes| Commit[\"Commit\"]\n  Compare -->|No| Conflict[\"No write\"]",
          "explanationMarkdown": "Inside Write, Match? compares Expected rev from Edit with Stored rev read inside the serialized operation.\nYes permits Commit, then Saved reports the new revision.\nNo produces No write: no temporary file, rename, or revision increment.\nAnother write cannot enter between this comparison and Commit.\nThe overview's recovery loop must read current content and reapply the intended change, not merely replace the revision number.\n\n```typescript\nif (expectedRevision !== currentRevision) {\n  return { error: \"Read again before retrying\" };\n}\n```"
        }
      ]
    },
    {
      "id": "process-note",
      "type": "markdown",
      "markdown": "## An uncertain response\n\nA missing write response does not prove that Commit failed.\nFor this recovery example, assume no competing writer during the check.\nPlanned update means the complete replacement and its expected next revision.\nRead compares both stored content and revision with that plan before another write is attempted.\nA changed revision alone does not prove that the planned content was saved.\nIf another writer can intervene or the result remains ambiguous, stop and investigate."
    },
    {
      "id": "process-response",
      "type": "diagram-deck",
      "title": "Interrupted response",
      "slides": [
        {
          "id": "process-response-slide",
          "title": "Check before another write",
          "mermaid": "flowchart TD\n  Read[\"Read\"] -->|stored state| Found{\"Saved?\"}\n  Planned[\"Planned update\"] --> Found\n  Found -->|Yes| Stop[\"No retry\"]\n  Found -->|No| Edit[\"Edit\"]",
          "explanationMarkdown": "Saved? compares the stored content and revision from Read with Planned update.\nYes means the planned replacement is present: No retry avoids a second write.\nNo returns to Edit with the current content and revision rather than resending the old request.\nThis read-only check does not verify Mermaid, math, readability, or content correctness."
        }
      ]
    },
    {
      "id": "process-conclusion",
      "type": "markdown",
      "markdown": "## Conclusion\n\nA replacement succeeds only after validation, a matching revision, and commit.\nOn conflict, read again and reapply the intended change.\nAfter an interrupted response, inspect stored content and revision before deciding whether to write again.\nAfter saving, open the viewer and check the full article and every slide at desktop and 390px, or report the missing coverage as unverified.\nKeep rendering, readability, source correctness, and human acceptance separate from storage success."
    }
  ]
}
