Degradation Ladder

Every challenge request walks down a four-tier ladder and serves the best tier available. The ladder exists so bot detection stays active even as the unlabeled item pool drains, and so the system never hard-blocks traffic when data is missing.

The four tiers

Tier 1 — Normal operation

Condition: ground-truth (GT) items exist and unlabeled items exist.

The solver sees two items: one GT item for verification and one unlabeled item for crowd annotation. A correct GT answer records the solver’s label for the unknown item. This is the labeling workhorse — all new items pass through Tier 1.

Tier 2 — Re-validation

Condition: GT items exist, no unlabeled items remain, but the re-validation pool is non-empty.

The unlabeled pool is exhausted, but previously labeled items haven’t yet accumulated enough evidence to graduate. The solver still sees two items — one GT item and one labeled item — and their answer is used to audit the existing label’s confidence. Bot detection remains fully active.

Tier 3 — GT only

Condition: GT items exist, but neither the unlabeled pool nor the re-validation pool has anything to offer.

The solver sees only a single GT item. The GT check still distinguishes bots from humans, but no labeling or re-validation work is done. This state means your dataset is fully graduated — all items have high confidence and sufficient vote volume.

Tier 4 — Fail-open

Condition: no GT items exist at all.

HiveGuard cannot generate a meaningful challenge. It returns HTTP 204 No Content with a bypass header so the client lets the request through without a token. This is the safety valve — blocking all traffic when the challenge system has no data would cause more damage than any bot.

204 No Content
X-HiveGuard-Bypass: no-gt-pool

Tier selection flow

Request arrives
    │
    ├─ GT items exist?  ──No──► Tier 4 (204 fail-open)
    │        │
    │       Yes
    │        │
    ├─ Unlabeled items exist?  ──Yes──► Tier 1 (label + verify)
    │        │
    │        No
    │        │
    ├─ Re-validation pool non-empty?  ──Yes──► Tier 2 (audit + verify)
    │        │
    │        No
    │        │
    └────────────────────────────────────────► Tier 3 (verify only)

When a widget token is bound to multiple datasets, HiveGuard evaluates every dataset independently and serves the lowest (best) tier available across all of them.

What to do at each tier

Tier	What it means	Action
1	Normal — labeling in progress	Nothing required
2	Unlabeled pool drained	Upload new unlabeled items if more labels are needed
3	All items graduated	Dataset is complete; optionally upload fresh items
4	No GT items	Upload ground-truth items immediately

Upload items:

hiveguard items upload ground_truth.jsonl --dataset <id>

Monitoring

hiveguard metrics

Check total_items and labeled_items. If total_items is 0 you’re at Tier 4. If labeled_items equals total_items and the re-validation pool is empty, you’re at Tier 3.