{"record":{"id":"52c85fb465a62366","repo":"affaan-m/ECC","slug":"only-a-dispatched-attempt-can-become-unknown","errorCode":null,"errorMessage":"only a dispatched attempt can become unknown","messagePattern":"only a dispatched attempt can become unknown","errorType":"validation","errorClass":"ClaimError","httpStatus":null,"severity":"error","filePath":"skills/operator-approval-loop/references/approval_claims.py","lineNumber":124,"sourceCode":"\ndef cancel(db, token, *, now):\n    \"\"\"Cancel only a not-yet-dispatched claim. Never reopen its decision key.\"\"\"\n    with _transaction(db, now):\n        row = _claim_row(db, token)\n        if row['state'] != 'claimed':\n            raise ClaimError('only a pre-dispatch claim can be cancelled')\n        db.execute(\"UPDATE obligation_delivery_claims SET state='cancelled',updated_ts=? WHERE token=?\",\n                   (now, token))\n\n\ndef mark_unknown(db, token, *, now):\n    \"\"\"Record uncertainty, including a restarted worker's dispatching claim.\"\"\"\n    with _transaction(db, now):\n        row = _claim_row(db, token)\n        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:","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/skills/operator-approval-loop/references/approval_claims.py#L106-L142","documentation":"mark_unknown() raises this ClaimError when the claim is not in the 'dispatching' state (and not already 'unknown', which returns silently). Only an attempt that was handed out by begin_dispatch and whose outcome is uncertain may be recorded as unknown; claims that were never dispatched, or that already finished, cannot become unknown.","triggerScenarios":"Calling mark_unknown(db, token) when state is 'claimed' (never dispatched), 'delivered' (already completed), or 'cancelled' — any state other than 'dispatching' or 'unknown'.","commonSituations":"Calling mark_unknown on a fresh token before begin_dispatch; a retry loop that calls mark_unknown after complete() already ran; misordering recovery logic in a restarted worker.","solutions":["Only call mark_unknown after a begin_dispatch that may or may not have taken effect (e.g. after a crash or transport timeout during dispatching).","Check state first: SELECT state FROM obligation_delivery_claims WHERE token=? and only mark unknown when state == 'dispatching'.","If state is 'unknown' already, no action is needed — the call is intentionally idempotent for that state.","If state is 'claimed', either begin_dispatch normally or cancel(); unknown is not the right transition."],"exampleFix":"// before: called blindly during recovery\nclaims.mark_unknown(db, token, now=ts)  # ClaimError when never dispatched\n\n// after\nrow = db.execute(\"SELECT state FROM obligation_delivery_claims WHERE token=?\", (token,)).fetchone()\nif row['state'] == 'dispatching':\n    claims.mark_unknown(db, token, now=ts)\nelif row['state'] == 'claimed':\n    claims.cancel(db, token, now=ts)","handlingStrategy":"validation","validationCode":"row = db.execute(\"SELECT state FROM obligation_delivery_claims WHERE token=?\", (token,)).fetchone()\nif row['state'] != 'dispatching':\n    return  # only a dispatched (and uncertain) attempt can become unknown","typeGuard":null,"tryCatchPattern":"try:\n    claims.mark_unknown(db, token, now=ts)\nexcept claims.ClaimError as e:\n    log.warning(\"mark_unknown refused for %s: %s\", token, e)","preventionTips":["Only call mark_unknown in crash/timeout recovery after a begin_dispatch","Branch recovery logic on the actual claim state","Remember 'unknown' marking is idempotent — no need to retry it"],"tags":["state-machine","recovery","crash-recovery","claim-token"],"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"}