Gaps fill up, fixes, ui restructuring
This commit is contained in:
master
104
docs/modules/policy/gates/beacon-rate-gate.md
Normal file
104
docs/modules/policy/gates/beacon-rate-gate.md
Normal file
@@ -0,0 +1,104 @@
|
||||
# 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.*
|
||||
96
docs/modules/policy/gates/execution-evidence-gate.md
Normal file
96
docs/modules/policy/gates/execution-evidence-gate.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# Execution Evidence Gate
|
||||
|
||||
**Gate ID:** `execution-evidence`
|
||||
|
||||
Enforces that an artifact has signed execution evidence from a specific environment before promotion. Ensures artifacts are observed running (with sufficient trace quality) before advancing through the release pipeline.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Checks if the target environment requires execution evidence (configurable per environment)
|
||||
2. Reads execution evidence metadata from the policy context
|
||||
3. If no evidence exists, applies the configured action (warn or block)
|
||||
4. If evidence exists, validates trace quality (minimum hot symbols and unique call paths)
|
||||
5. Returns pass, warn, or block result
|
||||
|
||||
## Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"PolicyGates": {
|
||||
"ExecutionEvidence": {
|
||||
"Enabled": false,
|
||||
"MissingEvidenceAction": "Warn",
|
||||
"RequiredEnvironments": ["production"],
|
||||
"MinHotSymbolCount": 3,
|
||||
"MinUniqueCallPaths": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Options
|
||||
|
||||
| Option | Type | Default | Description |
|
||||
|--------|------|---------|-------------|
|
||||
| `Enabled` | bool | `false` | Whether the gate is active (opt-in) |
|
||||
| `MissingEvidenceAction` | enum | `Warn` | Action when evidence is missing: `Warn` or `Block` |
|
||||
| `RequiredEnvironments` | string[] | `["production"]` | Environments that require execution evidence |
|
||||
| `MinHotSymbolCount` | int | `3` | Minimum hot symbols for sufficient trace quality |
|
||||
| `MinUniqueCallPaths` | int | `1` | Minimum unique call paths for sufficient trace quality |
|
||||
|
||||
## Context Metadata Keys
|
||||
|
||||
The gate reads the following keys from `PolicyGateContext.Metadata`:
|
||||
|
||||
| Key | Type | Description |
|
||||
|-----|------|-------------|
|
||||
| `has_execution_evidence` | `"true"/"false"` | Whether execution evidence exists |
|
||||
| `execution_evidence_hot_symbol_count` | int string | Number of hot symbols in the evidence |
|
||||
| `execution_evidence_unique_call_paths` | int string | Number of unique call paths |
|
||||
|
||||
## Example Gate Results
|
||||
|
||||
**Pass (evidence meets quality):**
|
||||
```
|
||||
Execution evidence meets quality thresholds (hot symbols: 42, call paths: 17)
|
||||
```
|
||||
|
||||
**Pass (environment not required):**
|
||||
```
|
||||
Execution evidence not required for environment 'staging'
|
||||
```
|
||||
|
||||
**Warn (no evidence, warn mode):**
|
||||
```
|
||||
No execution evidence found for this artifact (warn mode)
|
||||
```
|
||||
|
||||
**Fail (no evidence, block mode):**
|
||||
```
|
||||
No execution evidence found for this artifact in required environment
|
||||
```
|
||||
|
||||
**Fail (insufficient quality):**
|
||||
```
|
||||
Execution evidence trace quality is insufficient: hot symbols 1 < 3 or call paths 0 < 1
|
||||
```
|
||||
|
||||
## Integration
|
||||
|
||||
This gate consumes `stella.ops/executionEvidence@v1` predicates generated by the Signals execution evidence pipeline. Evidence is populated in the policy context during release evaluation.
|
||||
|
||||
Typical flow:
|
||||
1. Artifact runs in staging environment
|
||||
2. Signals captures runtime trace via eBPF/ETW
|
||||
3. `ExecutionEvidenceBuilder` generates signed predicate
|
||||
4. Release promotion to production triggers policy evaluation
|
||||
5. This gate verifies execution evidence exists from staging
|
||||
|
||||
## Related Documents
|
||||
|
||||
- `docs/contracts/execution-evidence-v1.md` — Predicate contract
|
||||
- `docs/modules/policy/gates/beacon-rate-gate.md` — Companion beacon rate gate
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2026-02-19.*
|
||||
Reference in New Issue
Block a user