{
  "env": {
    "recorded_at": "2026-08-15T08:52:04+00:00",
    "postgres": "PostgreSQL 16.13 (Homebrew)",
    "python": "3.12.12 (arm64)",
    "os": "Darwin 23.6.0",
    "commit": "eddf098"
  },
  "amount": 50,
  "scenarios": [
    {
      "key": "naive",
      "title": "The way most people write it",
      "subtitle": "Dedup state lives in process memory",
      "approach": "naive",
      "steps": [
        {
          "n": 1,
          "kind": "start",
          "title": "A customer needs to be charged $50.",
          "detail": "The worker keeps a set of task ids it has already charged, so a retry will not charge twice.",
          "proof": null,
          "ledger": 0,
          "task_state": null,
          "at_ms": 3.3
        },
        {
          "n": 2,
          "kind": "crash",
          "title": "The worker is hard-killed the instant after the charge commits.",
          "detail": "kill -9 \u2014 the process gets no chance to clean up, and its in-memory set of already-charged tasks dies with it.",
          "proof": {
            "kind": "shell",
            "cmd": "$ python scripts/naive_worker.py --task-id naive-1 --crash-at after_commit",
            "out": "killed by signal 9 (SIGKILL)"
          },
          "ledger": 50,
          "task_state": null,
          "at_ms": 97.8
        },
        {
          "n": 3,
          "kind": "observe",
          "title": "The charge did land: $50.",
          "detail": "Postgres has the row. The worker's memory of having made it does not exist anywhere anymore.",
          "proof": {
            "kind": "sql",
            "cmd": "SELECT coalesce(sum(amount), 0) FROM naive_ledger WHERE task_id = 'naive-1'",
            "out": "50"
          },
          "ledger": 50,
          "task_state": null,
          "at_ms": 98.2
        },
        {
          "n": 4,
          "kind": "recover",
          "title": "A retry starts, as any queue or supervisor would do.",
          "detail": "New process, fresh empty set. It checks whether it already charged this task, finds nothing, and charges again.",
          "proof": {
            "kind": "shell",
            "cmd": "$ python scripts/naive_worker.py --task-id naive-1",
            "out": "exit 0, printed 'charged'"
          },
          "ledger": null,
          "task_state": null,
          "at_ms": 196.9
        },
        {
          "n": 5,
          "kind": "verdict",
          "title": "The customer was charged $100.",
          "detail": "Two rows in the ledger for one job. This is a real double charge, not a hypothetical one.",
          "proof": {
            "kind": "sql",
            "cmd": "SELECT coalesce(sum(amount), 0) FROM naive_ledger WHERE task_id = 'naive-1'",
            "out": "100"
          },
          "ledger": 100,
          "task_state": null,
          "at_ms": 197.6
        }
      ],
      "result": {
        "charged": 100,
        "expected": 50,
        "verdict": "double charged",
        "ok": false
      }
    },
    {
      "key": "hapax_before_commit",
      "title": "Hapax, killed before the charge commits",
      "subtitle": "The worst moment: mid-transaction",
      "approach": "hapax",
      "steps": [
        {
          "n": 1,
          "kind": "start",
          "title": "The same $50 charge, now as a Hapax task.",
          "detail": "The task's state lives in Postgres, not in the worker.",
          "proof": {
            "kind": "sql",
            "cmd": "SELECT state FROM tasks WHERE id = 'task_88e6d556692840e8a04f99b7080b00a6'",
            "out": "working"
          },
          "ledger": 0,
          "task_state": "working",
          "at_ms": 7.3
        },
        {
          "n": 2,
          "kind": "crash",
          "title": "The worker is hard-killed mid-transaction.",
          "detail": "The charge has been written but not committed. The kill is a real SIGKILL, so the database connection simply drops.",
          "proof": {
            "kind": "shell",
            "cmd": "$ python -m hapax.worker --task-id task_88e6d556692840e8a04f99b7080b00a6 --crash-at before_commit",
            "out": "killed by signal 9 (SIGKILL)"
          },
          "ledger": null,
          "task_state": null,
          "at_ms": 100.9
        },
        {
          "n": 3,
          "kind": "observe",
          "title": "Postgres rolled the whole transaction back: ledger $0.",
          "detail": "The charge and the 'this task is done' flag were written in one transaction, so neither survived. The task is honestly still working.",
          "proof": {
            "kind": "sql",
            "cmd": "SELECT coalesce(sum(amount), 0) FROM ledger WHERE task_id = 'task_88e6d556692840e8a04f99b7080b00a6'",
            "out": "0"
          },
          "ledger": 0,
          "task_state": "working",
          "at_ms": 103.4
        },
        {
          "n": 4,
          "kind": "recover",
          "title": "A retry picks the task up and runs it cleanly.",
          "detail": "Nothing was half-done, so there is nothing to reconcile.",
          "proof": {
            "kind": "shell",
            "cmd": "$ python -m hapax.worker --task-id task_88e6d556692840e8a04f99b7080b00a6",
            "out": "exit 0, printed 'completed'"
          },
          "ledger": null,
          "task_state": "completed",
          "at_ms": 209.5
        },
        {
          "n": 5,
          "kind": "verdict",
          "title": "The customer was charged $50. Exactly once.",
          "detail": "One row. The crash cost a retry, not a duplicate charge.",
          "proof": {
            "kind": "sql",
            "cmd": "SELECT coalesce(sum(amount), 0) FROM ledger WHERE task_id = 'task_88e6d556692840e8a04f99b7080b00a6'",
            "out": "50"
          },
          "ledger": 50,
          "task_state": "completed",
          "at_ms": 210.6
        }
      ],
      "result": {
        "charged": 50,
        "expected": 50,
        "verdict": "charged exactly once",
        "ok": true
      }
    },
    {
      "key": "hapax_after_commit",
      "title": "Hapax, killed after the charge commits",
      "subtitle": "The moment that breaks the naive version",
      "approach": "hapax",
      "steps": [
        {
          "n": 1,
          "kind": "start",
          "title": "The same $50 charge again.",
          "detail": "This time the kill lands after the money has already moved \u2014 the case that double-charged the naive worker.",
          "proof": {
            "kind": "sql",
            "cmd": "SELECT state FROM tasks WHERE id = 'task_ea5592ac71674862acd5207c1b9e40bf'",
            "out": "working"
          },
          "ledger": 0,
          "task_state": "working",
          "at_ms": 0.9
        },
        {
          "n": 2,
          "kind": "crash",
          "title": "The worker charges, commits, and is hard-killed immediately after.",
          "detail": "Same kill -9, same instant as the naive run.",
          "proof": {
            "kind": "shell",
            "cmd": "$ python -m hapax.worker --task-id task_ea5592ac71674862acd5207c1b9e40bf --crash-at after_commit",
            "out": "killed by signal 9 (SIGKILL)"
          },
          "ledger": null,
          "task_state": null,
          "at_ms": 114.1
        },
        {
          "n": 3,
          "kind": "observe",
          "title": "The charge landed ($50) and the task is completed.",
          "detail": "Both were committed together, so the record of the work is as durable as the work itself.",
          "proof": {
            "kind": "sql",
            "cmd": "SELECT coalesce(sum(amount), 0) FROM ledger WHERE task_id = 'task_ea5592ac71674862acd5207c1b9e40bf'",
            "out": "50"
          },
          "ledger": 50,
          "task_state": "completed",
          "at_ms": 115.7
        },
        {
          "n": 4,
          "kind": "recover",
          "title": "The retry starts and immediately declines to do anything.",
          "detail": "It reads the task from Postgres, sees a terminal state, and stops. 'noop-terminal' is the worker refusing to charge a second time.",
          "proof": {
            "kind": "shell",
            "cmd": "$ python -m hapax.worker --task-id task_ea5592ac71674862acd5207c1b9e40bf",
            "out": "exit 0, printed 'noop-terminal'"
          },
          "ledger": null,
          "task_state": null,
          "at_ms": 232.0
        },
        {
          "n": 5,
          "kind": "verdict",
          "title": "The customer was charged $50. Exactly once.",
          "detail": "Same crash that cost the naive worker $50 of someone else's money.",
          "proof": {
            "kind": "sql",
            "cmd": "SELECT coalesce(sum(amount), 0) FROM ledger WHERE task_id = 'task_ea5592ac71674862acd5207c1b9e40bf'",
            "out": "50"
          },
          "ledger": 50,
          "task_state": "completed",
          "at_ms": 233.6
        }
      ],
      "result": {
        "charged": 50,
        "expected": 50,
        "verdict": "charged exactly once",
        "ok": true
      }
    }
  ]
}