Skip to content
bucker

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.