# The trust check

Before an insight made by an agent is shared, certified or alerted on, Bucker counts what is wrong with the data under it. The trust check is a deterministic gate, not advice: each line is `pass`, `warn`, `fail` or `not_checked`, with counts and the rule version, and a `fail` blocks sharing the insight and alerting on it until a person overrides it with a reason.

It reads the newest seven days of the data an insight's node reads. It runs only while product analytics is enabled for the project (the data-processing gate); with the gate shut it refuses and stores nothing.

## The lines

| Line | What it counts |
| --- | --- |
| `internal_traffic` | Subjects and accounts the project's internal filter recognises, among those active in the window. With no filter configured the line is `not_checked`, never `pass`. |
| `development_environments` | Sessions in a development, test or CI environment. |
| `localhost_hosts` | Sessions that entered from a localhost referrer. |
| `bots` | Sessions whose actor type is not a person (bots, automated browsers). |
| `duplicate_uuids` | Events the 48-hour uuid ledger caught a second time. |
| `ingest_drops` | Product events the door refused (rate, quota, size, invalid). |
| `sampled_items` | Product events the sampler kept only a fraction of. |
| `quarantined_events` | Events held by the door or an ingestion filter, counted in no insight. |
| `personless_share` | Events with no person on them. |
| `clock_skew` | Events whose timestamp the door had to correct. |

A line says `not_checked` (with the reason) where nothing was measured, because a zero that means "nobody looked" is the failure the check exists to prevent. The overall status is `fail` when any line fails, `warn` when any line warns or is not checked, and `pass` only when every line was measured and clean. The rule version (`pa09-2`) names the threshold table and is part of every digest; `pa09-2` is the change that reports the `bots` line of a Humans-only node the rollups cannot filter as a warning carrying `actor_exclusion_unavailable`.

**Humans only, when it cannot be applied.** In this release the door does not stamp `humans_only` on a new insight (H-366: field first, stamp second; the follow-up release turns the stamp on), so a node is humans-only only when the caller asks. For such a node, and for every new insight once the stamp is on, until the columnar lane serves its node the rollups keep no actor type, so the answer still counts agents, bots and unclassified traffic. The `bots` line cannot fail the check: a share that would fail is reported as `warn`, its note begins `actor_exclusion_unavailable:` and says what the numbers still count, and the line's counts carry `actorExclusionApplied: false`. The plan an approver reads lists the same warning beside the gate, so a share is never silently unfiltered and never refused for a reason its owner cannot fix. A node that sets `humans_only: false` has opted out of the filter and keeps the failure.

The result carries a digest: a hash of the rule version, the node, the window, the lines, their counts and the internal filter. Re-running over unchanged data gives the same digest. The digest travels in the insight envelope's `trustCheckDigest` and in the plan digest of `insight.create` and `alert_rule.create`, so a plan approved on one result is invalidated by a change in the data under it. Results are kept 90 days.

## Overrides

A person who is a project admin may accept a failing check for one node, either the whole check or one failing line, with a reason (500 characters) and an end date (30 days by default, 90 at most). The act is `trust_check.override` and is human-only: it is refused to every agent, service and OAuth-client token. Anyone who may write analytics, an agent included, can end an override with `trust_check_override.revoke`: it only makes the gate stricter, so it applies without an approval.

## The internal filter

A project describes its own staff and test traffic with a closed grammar of at most 20 conditions over subject property values, the subject's email and account properties. A subject is internal when any condition matches. The conditions name staff domains and test-account values, so agents never read them: there is no MCP tool, the project setting reports only that a filter exists and how many conditions it holds, and the conditions are returned only to a person's own session. Setting it (`internal_filter.update`) asks for approval, and each write keeps the filter it replaced in its audit row.

## API

| Route | Purpose |
| --- | --- |
| `POST /orgs/:org/projects/:project/analytics/trust-check` | Run and store the check for a node or a saved insight. |
| `POST .../analytics/trust-check/override` | A person accepts a failing check (human-only, project admin). |
| `POST .../analytics/trust-check/override/revoke` | End an override (governed, safety-increasing). |
| `GET/PUT .../analytics/internal-filter` | Read or set the filter (person's session only). |

## MCP

`trust_check_get` (analytics toolset, read-only) returns each check with its status, counts and the rule version, and lists the checks that were not checked. Text that originates outside Bucker is sanitized and named in `trust.untrustedFields`.
