# Production assertions

Some of the costliest bugs throw nothing: a double charge, a wrong total, a skipped email. An error
tracker sees exceptions and APM sees latency, so these reach the support desk first. Production
assertions let your code state a rule and let Bucker count whether it held, per release.

Assertions are **opt-in code you write**. Nothing is collected until you add a call, and the calls
never throw into the code they guard.

## The three calls

```ts
import { assertAlways, assertSometimes, assertUnreachable } from '@bucker/sdk-core/assertions'

assertAlways('checkout.total', order.total === sum(order.lines), { total: order.total })
assertSometimes('cache.hit', hit)               // is it ever true?
assertUnreachable('legacy.path', { route })     // reaching this line is a violation
```

```python
from bucker_sdk import assert_always, assert_sometimes, assert_unreachable

assert_always("checkout.total", order.total == sum(order.lines), {"total": order.total})
```

Each returns its condition unchanged, so it can sit inside an expression. The id is a short name you
choose (`[A-Za-z0-9][A-Za-z0-9._:/-]{0,95}`); it is on the wire and in the issue's fingerprint.

## What leaves the process

- **Passes are counted in process**, per assertion id and minute. One `assertion_counters` item a
  minute carries **ids and counts only**: evaluations, violations and (for `sometimes`) how often it
  held. There is no operand, no text and no project in it; the project is the key's.
- **Only a violation sends an event.** It carries the operands you passed, rendered through the
  state-slice projection and scrubbed at both tiers. At most five violation events leave per minute
  per process; the counter still counts every one.
- With no client configured, nothing is counted and nothing is sent.

## What Bucker does with it

- A violation is an **ordinary issue**, fingerprinted on the assertion id, so it triages, assigns,
  resolves and alerts like any other. Paging on one is an ordinary alert rule.
- **Release health** shows **violations per million evaluations** beside the crash-free rate, for
  `always` and `unreachable` assertions. A release that no assertion ran in has a null rate, never zero.
  The rate is not available with an environment filter: counters carry no environment.
- A **`sometimes` assertion that never held in a release** is reported, flagged `lowSample` below 30
  evaluations so a thin count is not read as a verdict.
- Agents read the per-assertion, per-release view with the `assertions_list` tool (read, `event:read`).
  Its assertion ids, release labels and issue titles come from your code and are served as untrusted text.

## Proposed assertions

When an issue caused by silent wrongness is resolved, the remediation lane may propose the assertion
that would have caught it, in the ladder category `assertion_add`. The proposal is only made after
it **fails on the code the issue lived in and passes on the fix**: an assertion that is never
evaluated, held before the fix, failed for another reason, or still fails after the fix is refused
with the reason. It is opened as a **draft pull request**; the category never goes above `DRAFT_PR`
and Bucker never merges. You merge it, and you decide which assertions page.

## Limits

Counter rows per item are bounded, per-row counts are bounded, a minute outside a window of five
minutes ahead and seven days behind is discarded, and replays of the same item add their counts again
(the rate is unchanged by a replay; only absolute counts drift).
