# 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.*