{"record":{"id":"73eab5d2ee4e83b8","repo":"affaan-m/ECC","slug":"completion-contradicts-the-existing-receipt","errorCode":null,"errorMessage":"completion contradicts the existing receipt","messagePattern":"completion contradicts the existing receipt","errorType":"validation","errorClass":"ClaimError","httpStatus":null,"severity":"error","filePath":"skills/operator-approval-loop/references/approval_claims.py","lineNumber":139,"sourceCode":"        if row['state'] == 'unknown':\n            return\n        if row['state'] != 'dispatching':\n            raise ClaimError('only a dispatched attempt can become unknown')\n        db.execute(\"UPDATE obligation_delivery_claims SET state='unknown',updated_ts=? WHERE token=?\",\n                   (now, token))\n\n\ndef _finish(db, token, coordinate, now, evidence):\n    if not isinstance(coordinate, str) or not coordinate.strip():\n        raise ClaimError('a confirmed nonempty coordinate is required')\n    with _transaction(db, now):\n        row = _claim_row(db, token)\n        receipt = db.execute('''SELECT * FROM obligation_deliveries\n            WHERE obligation_id=? AND decision_id=?''',\n                             (row['obligation_id'], row['decision_id'])).fetchone()\n        if row['state'] == 'delivered':\n            if receipt is None or receipt['coordinate'] != coordinate or receipt['kind'] != 'draft_sent':\n                raise ClaimError('completion contradicts the existing receipt')\n            return False\n        expected_state = 'dispatching' if evidence is None else 'unknown'\n        if row['state'] != expected_state:\n            raise ClaimError('completion requires the correct dispatch/reconciliation state')\n        _snapshot(db, row['obligation_id'], row['decision_id'])\n        db.execute('''INSERT INTO obligation_deliveries\n            (obligation_id,decision_id,kind,coordinate,delivered_ts) VALUES (?,?,'draft_sent',?,?)''',\n                   (row['obligation_id'], row['decision_id'], coordinate, now))\n        db.execute('''UPDATE obligation_delivery_claims\n            SET state='delivered',updated_ts=?,reconciliation_evidence=? WHERE token=?''',\n                   (now, evidence, token))\n        changed = db.execute(\"UPDATE obligations SET status='sent' WHERE id=? AND status='approved'\",\n                             (row['obligation_id'],)).rowcount\n        if changed != 1:\n            raise ClaimError('obligation completion failed')\n    return True\n\n","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/skills/operator-approval-loop/references/approval_claims.py#L121-L157","documentation":"_finish raises this when the claim row already reads 'delivered' but the existing receipt does not match the completion being replayed: no receipt row exists, the coordinate differs, or the receipt kind is not 'draft_sent'. Identical duplicate completions are idempotent no-ops; any mismatch is treated as contradictory evidence and refused.","triggerScenarios":"Calling complete()/reconcile() twice for the same token with a different coordinate; the receipt row was deleted or written by another writer with a different kind; passing a typo'd or alternate coordinate on retry.","commonSituations":"Retry logic that regenerates the coordinate (e.g. a new message ID per attempt) instead of reusing the original; two workers finishing the same claim with different delivery artifacts; manual DB edits to obligation_deliveries.","solutions":["Reuse the exact original coordinate string when replaying a completion after a timeout or crash.","Check the existing receipt first (SELECT coordinate, kind FROM obligation_deliveries WHERE obligation_id=? AND decision_id=?) and compare before finishing.","If the second coordinate is genuinely a different delivery, do not finish the same claim — the claim is already delivered; handle the extra delivery at the business level.","Restore/remove any hand-edited receipt rows so the stored receipt reflects the real delivery."],"exampleFix":"// before: retry builds a fresh coordinate\nretry: claims.complete(db, token, str(new_message_id), now=ts2)  # ClaimError\n\n// after: persist and replay the same coordinate\noriginal_coordinate = str(first_send.id)\ntry:\n    claims.complete(db, token, original_coordinate, now=ts1)\nexcept TimeoutError:\n    claims.complete(db, token, original_coordinate, now=ts2)  # idempotent no-op","handlingStrategy":"validation","validationCode":"receipt = db.execute(\"SELECT coordinate, kind FROM obligation_deliveries WHERE obligation_id=? AND decision_id=?\", (oid, did)).fetchone()\nif receipt and (receipt['coordinate'] != coordinate or receipt['kind'] != 'draft_sent'):\n    raise ValueError(\"retry coordinate differs from recorded receipt\")","typeGuard":null,"tryCatchPattern":"try:\n    claims.complete(db, token, coordinate, now=ts)\nexcept claims.ClaimError:\n    log.error(\"completion contradicts recorded receipt; investigate before retrying\")","preventionTips":["Persist the original coordinate and reuse it verbatim on retries","Never regenerate delivery identifiers in a retry loop","Do not hand-edit obligation_deliveries rows"],"tags":["idempotency","state-machine","receipt-mismatch","retry"],"backgroundTag":"invalid-state-transition","analyzedSha":"8321021c54d670126ce3b2969d5deb880b4b0c2a","analyzedAt":"2026-09-16T10:08:13.343Z","contentChangedAt":"2026-09-16T10:08:13.343Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}