# 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.

```python
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.

```python
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.