105 lines
3.4 KiB
Markdown
105 lines
3.4 KiB
Markdown
# Beacon Verification Rate Gate
|
||
|
||
**Gate ID:** `beacon-rate`
|
||
|
||
Enforces minimum beacon verification rate for runtime canary coverage. When enabled, blocks or warns for releases where beacon coverage is insufficient in a required environment.
|
||
|
||
## How It Works
|
||
|
||
1. Checks if the target environment requires beacon coverage (configurable per environment)
|
||
2. Reads beacon telemetry data from the policy context
|
||
3. If no beacon data exists, applies the configured missing-beacon action (warn or block)
|
||
4. If beacon count is below the minimum, defers rate enforcement (insufficient sample size)
|
||
5. Compares verification rate against threshold, returns pass, warn, or block
|
||
|
||
## Configuration
|
||
|
||
```json
|
||
{
|
||
"PolicyGates": {
|
||
"BeaconRate": {
|
||
"Enabled": false,
|
||
"BelowThresholdAction": "Warn",
|
||
"MissingBeaconAction": "Warn",
|
||
"MinVerificationRate": 0.8,
|
||
"RequiredEnvironments": ["production"],
|
||
"MinBeaconCount": 10
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Options
|
||
|
||
| Option | Type | Default | Description |
|
||
|--------|------|---------|-------------|
|
||
| `Enabled` | bool | `false` | Whether the gate is active (opt-in) |
|
||
| `BelowThresholdAction` | enum | `Warn` | Action when rate is below threshold: `Warn` or `Block` |
|
||
| `MissingBeaconAction` | enum | `Warn` | Action when no beacon data exists: `Warn` or `Block` |
|
||
| `MinVerificationRate` | double | `0.8` | Minimum acceptable verification rate (0.0–1.0) |
|
||
| `RequiredEnvironments` | string[] | `["production"]` | Environments requiring beacon coverage |
|
||
| `MinBeaconCount` | int | `10` | Minimum beacons before rate enforcement applies |
|
||
|
||
## Context Metadata Keys
|
||
|
||
The gate reads the following keys from `PolicyGateContext.Metadata`:
|
||
|
||
| Key | Type | Description |
|
||
|-----|------|-------------|
|
||
| `beacon_verification_rate` | double string | Verification rate (0.0–1.0) |
|
||
| `beacon_verified_count` | int string | Number of verified beacon events |
|
||
|
||
## Beacon Verification States
|
||
|
||
| State | Description | Default Behavior |
|
||
|-------|-------------|------------------|
|
||
| No data | No beacon telemetry available | Depends on `MissingBeaconAction` |
|
||
| Insufficient count | Fewer beacons than `MinBeaconCount` | Rate enforcement deferred (pass with warning) |
|
||
| Below threshold | Rate < `MinVerificationRate` | Depends on `BelowThresholdAction` |
|
||
| Above threshold | Rate >= `MinVerificationRate` | Pass |
|
||
|
||
## Example Gate Results
|
||
|
||
**Pass:**
|
||
```
|
||
Beacon verification rate (95.0%) meets threshold (80.0%)
|
||
```
|
||
|
||
**Pass (environment not required):**
|
||
```
|
||
Beacon rate not required for environment 'dev'
|
||
```
|
||
|
||
**Pass (insufficient sample):**
|
||
```
|
||
Beacon count (3) below minimum (10); rate enforcement deferred
|
||
```
|
||
|
||
**Warn (below threshold):**
|
||
```
|
||
Beacon verification rate (60.0%) is below threshold (warn mode)
|
||
```
|
||
|
||
**Fail (no data, block mode):**
|
||
```
|
||
No beacon telemetry data available for this artifact
|
||
```
|
||
|
||
**Fail (below threshold, block mode):**
|
||
```
|
||
Beacon verification rate (60.0%) is below threshold (80.0%)
|
||
```
|
||
|
||
## Integration
|
||
|
||
This gate consumes beacon verification rate data derived from `stella.ops/beaconAttestation@v1` predicates. The rate is computed by the Signals beacon pipeline as `verified_beacons / expected_beacons` over a configurable lookback window.
|
||
|
||
## Related Documents
|
||
|
||
- `docs/contracts/beacon-attestation-v1.md` — Predicate contract
|
||
- `docs/modules/policy/gates/execution-evidence-gate.md` — Companion execution evidence gate
|
||
|
||
---
|
||
|
||
*Last updated: 2026-02-19.*
|