{"record":{"id":"6bb73f31b5576b99","repo":"affaan-m/ECC","slug":"unknown-claim-token","errorCode":null,"errorMessage":"unknown claim token","messagePattern":"unknown claim token","errorType":"validation","errorClass":"ClaimError","httpStatus":null,"severity":"error","filePath":"skills/operator-approval-loop/references/approval_claims.py","lineNumber":74,"sourceCode":"    try:\n        digest = hashlib.sha256(row['draft_text'].encode('utf-8')).hexdigest()\n    except (AttributeError, UnicodeError) as error:\n        raise ClaimError('approved text must be valid UTF-8 text') from error\n    stored_digest = row['draft_sha256']\n    if (not isinstance(stored_digest, str) or len(stored_digest) != 64\n            or any(character not in '0123456789abcdef' for character in stored_digest)):\n        raise ClaimError('approved hash must be lowercase SHA-256 hexadecimal')\n    if not secrets.compare_digest(digest, stored_digest):\n        raise ClaimError('approved text hash does not match')\n    return dict(row)\n\n\ndef _claim_row(db, token):\n    if not isinstance(token, str) or not token:\n        raise ClaimError('a claim token is required')\n    row = db.execute('SELECT * FROM obligation_delivery_claims WHERE token=?', (token,)).fetchone()\n    if row is None:\n        raise ClaimError('unknown claim token')\n    return row\n\n\ndef claim(db, obligation_id, decision_id, *, now):\n    \"\"\"Reserve one already-authorized decision; return only a random claim token.\"\"\"\n    with _transaction(db, now):\n        _snapshot(db, obligation_id, decision_id)\n        token = secrets.token_hex(32)\n        db.execute('''INSERT INTO obligation_delivery_claims\n            (obligation_id,decision_id,token,state,created_ts,updated_ts)\n            VALUES (?,?,?,'claimed',?,?)''', (obligation_id, decision_id, token, now, now))\n    return token\n\n\ndef begin_dispatch(db, token, *, now):\n    \"\"\"Return bound payload once, only after dispatching state has committed.\n\n    A crash after this boundary is uncertain even if transport has not started.","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/affaan-m/ECC/blob/8321021c54d670126ce3b2969d5deb880b4b0c2a/skills/operator-approval-loop/references/approval_claims.py#L56-L92","documentation":"After validating the token format, the library looks it up in obligation_delivery_claims. If no row matches, the token does not correspond to any claim this database issued, so the operation is refused. This keeps dispatch/cancel/unknown-marking strictly tied to claims created by claim() in the same database.","triggerScenarios":"Passing a token from a different database/environment; a typo'd or truncated token; the claim row was deleted; calling cancel/mark_unknown twice after the row was purged by a cleanup job.","commonSituations":"Replaying tokens recorded in logs from another environment (staging vs prod); multi-worker setups where each worker uses its own DB file; retyping a token by hand from a console message; tests reusing fixtures across DBs.","solutions":["Verify the token exists: SELECT * FROM obligation_delivery_claims WHERE token=? before calling","Confirm you are connected to the same database that issued the token","Use the full, exact token string returned by claim() (64 hex chars from secrets.token_hex(32)) — copy it, don't retype it","If the claim row is gone, re-create it via the approval + claim flow; there is no way to resurrect a deleted token"],"exampleFix":"// before\nbegin_dispatch(db, token_from_other_env, now=ts)  # unknown claim token\n\n// after\nexists = db.execute('SELECT 1 FROM obligation_delivery_claims WHERE token=?', (token,)).fetchone()\nif not exists:\n    raise AppError('token not found in this database; check environment')\nbegin_dispatch(db, token, now=ts)","handlingStrategy":"try-catch","validationCode":"def token_known(db, token) -> bool:\n    return db.execute('SELECT 1 FROM obligation_delivery_claims WHERE token=?',\n                      (token,)).fetchone() is not None","typeGuard":null,"tryCatchPattern":"try:\n    cancel(db, token, now=ts)\nexcept ClaimError as e:\n    if 'unknown claim token' in str(e):\n        log.warning('token %s... not found; wrong DB or expired claim', token[:8])\n        # safe to treat as already-resolved for cancel; escalate for dispatch\n    else:\n        raise","preventionTips":["Store tokens only in the DB that issued them; tag records with the DB/environment","Copy the full 64-char token verbatim; never retype or truncate","Avoid cleanup jobs that delete obligation_delivery_claims rows still referenced by workers","In multi-DB setups, look up the issuing database before dispatch/cancel operations"],"tags":["sqlite","tokens","record-not-found"],"backgroundTag":"resource-not-found","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"}