diagnostics #

Diagnostics exist to keep a claim about what happened separate from what you actually saw happen. Two facts drive everything here: a synchronous call you awaited already ran, and an unknown effect never justifies a replay.

the trail #

You awaited something that was not awaitable, and it raised. The tempting reading is "it errored, so nothing happened". For a synchronous call the mutation committed before the TypeError was raised.

from klbr import diagnostic

try:
    await save_everything()
except TypeError as error:
    diagnosis = diagnostic.diagnose_await_failure(
        save_everything,
        error,
        effect_verifier=lambda: receipt_exists("save"),
    )
    print(diagnosis.function_executed, diagnosis.effect_status, diagnosis.can_replay)
    print(diagnosis.prescribed_action)

effect_status is three-valued: present, absent, or unknown. can_replay is true only for absent and a function that never ran. A verifier that itself raises produces unknown, and unknown is not permission.

When you are writing the mutation rather than diagnosing it, safe_execute_mutation applies the same rule: an effect already present means the call is not repeated.

capability honesty #

A check result is scoped, and the scope is part of the answer.

from klbr import checks

result = checks.check_resource_access(source_path, draft_path)
print(result.status, result.effective_status(), result.evidence, result.valid_until_s)

healthy carries an expiry and becomes stale after it. degraded must name the impact. unavailable must name the dependency. unknown must name the missing evidence. unknown is a supported answer, not a failed check - and it is never a pass.

Repeated failures are grouped before they are reported: group_failure_observations deduplicates by operation, revision, signature, and workspace, and gives each group a stable action_identity, so a second report is recognizably the first one.

refusals #

Nothing here will tell you an effect is absent when it could not check. An expired healthy is not healthy, and a probe you could not run is not evidence of anything.