affaan-m/ECC · error · ClaimError

trusted reconciliation evidence is required

Error message

trusted reconciliation evidence is required

What it means

reconcile() raises this ClaimError when the evidence argument is not a nonempty string. The module is a reference implementation that never verifies outcomes itself; it therefore demands the trusted caller supply explicit, nonempty outcome evidence that is stored on the claim (reconciliation_evidence) as an audit record.

Solutions

1. Supply a nonempty string describing the verified outcome (e.g. transport receipt ID, operator attestation reference).
2. Validate before calling: isinstance(evidence, str) and evidence.strip().
3. Capture evidence at the point of verification (from the transport layer's response) rather than passing a placeholder.
4. If no trusted evidence exists, do not reconcile — leave the claim 'unknown'; there is deliberately no path to resolve unknowns without evidence.

Example fix

// before
claims.reconcile(db, token, coordinate, True, now=ts)  # non-string evidence

// after
evidence = f"transport_receipt:{receipt.id}"
if not (isinstance(evidence, str) and evidence.strip()):
    raise ValueError("reconciliation evidence required")
claims.reconcile(db, token, coordinate, evidence, now=ts)

def validate_evidence(evidence):
    return isinstance(evidence, str) and bool(evidence.strip())

if not validate_evidence(evidence):
    raise ValueError("reconcile requires nonempty trusted evidence")

def is_nonempty_str(value):
    return isinstance(value, str) and value.strip() != ""

try:
    claims.reconcile(db, token, coordinate, evidence, now=ts)
except claims.ClaimError:
    log.error("reconciliation refused; evidence missing or empty")

When it happens

Trigger: reconcile(db, token, coordinate, None, now=...), reconcile(db, token, coordinate, "", now=...), or evidence as whitespace/bytes/other non-str type.

Common situations: An operator pipeline that has no evidence variable populated; passing a boolean or an ID object instead of an evidence string; wiring reconcile into automation before the evidence-capture step exists.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• a confirmed nonempty coordinate is required
• harness health evidence exceeds integrity verification bound
• harness health evidence is inconsistent with audit outcome
• skill_id is required
• skill_version is required

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/e10d24305715a1c4. Report an issue: GitHub.

Appendix: source

Thrown at skills/operator-approval-loop/references/approval_claims.py:170

                             (row['obligation_id'],)).rowcount
        if changed != 1:
            raise ClaimError('obligation completion failed')
    return True


def complete(db, token, coordinate, *, now):
    """Atomically record a confirmed result; identical duplicate completion is a no-op."""
    return _finish(db, token, coordinate, now, None)


def reconcile(db, token, coordinate, evidence, *, now):
    """Trusted caller supplies verified outcome evidence; this does not verify it.

    No cancellation/retry of unknown claims is provided: a paused original
    executor could still act. Operator authentication is outside this reference.
    """
    if not isinstance(evidence, str) or not evidence.strip():
        raise ClaimError('trusted reconciliation evidence is required')
    return _finish(db, token, coordinate, now, evidence)

View on GitHub (pinned to 8321021c54)