git.stella-ops.org/docs/modules/policy/budget-attestation.md

# Budget Threshold Attestation

This document describes how unknown budget thresholds are attested in verdict bundles for reproducibility and audit purposes.

## Overview

Budget attestation captures the budget configuration applied during policy evaluation, enabling:

- **Auditability**: Verify what thresholds were enforced at decision time
- **Reproducibility**: Include all inputs for deterministic verification
- **Compliance**: Demonstrate policy enforcement for regulatory requirements

## Budget Check Predicate

The budget check is included in the verdict predicate:

```json
{
  "_type": "https://stellaops.dev/predicates/policy-verdict@v1",
  "tenantId": "tenant-1",
  "policyId": "default-policy",
  "policyVersion": 1,
  "verdict": { ... },
  "budgetCheck": {
    "environment": "production",
    "config": {
      "maxUnknownCount": 10,
      "maxCumulativeUncertainty": 2.5,
      "action": "warn",
      "reasonLimits": {
        "Reachability": 5,
        "Identity": 3
      }
    },
    "actualCounts": {
      "total": 3,
      "cumulativeUncertainty": 1.2,
      "byReason": {
        "Reachability": 2,
        "Identity": 1
      }
    },
    "result": "pass",
    "configHash": "sha256:abc123...",
    "evaluatedAt": "2025-12-25T12:00:00Z",
    "violations": []
  }
}
```

## Fields

### budgetCheck.config

| Field | Type | Description |
|-------|------|-------------|
| `maxUnknownCount` | int | Maximum total unknowns allowed |
| `maxCumulativeUncertainty` | double | Maximum uncertainty score |
| `action` | string | Action when exceeded: warn, block |
| `reasonLimits` | object | Per-reason code limits |

### budgetCheck.actualCounts

| Field | Type | Description |
|-------|------|-------------|
| `total` | int | Total unknowns observed |
| `cumulativeUncertainty` | double | Sum of uncertainty factors |
| `byReason` | object | Breakdown by reason code |

### budgetCheck.result

Possible values:
- `pass` - All limits satisfied
- `warn` - Limits exceeded but action is warn
- `fail` - Limits exceeded and action is block

### budgetCheck.configHash

SHA-256 hash of the budget configuration for determinism verification. Format: `sha256:{64 hex characters}`

### budgetCheck.violations

List of violations when limits are exceeded:

```json
{
  "violations": [
    {
      "type": "total",
      "limit": 10,
      "actual": 15
    },
    {
      "type": "reason",
      "limit": 5,
      "actual": 8,
      "reason": "Reachability"
    }
  ]
}
```

## Usage

### Extracting Budget Check from Verdict

```csharp
using StellaOps.Policy.Engine.Attestation;

// Parse verdict predicate from DSSE envelope
var predicate = VerdictPredicate.Parse(dssePayload);

// Access budget check
if (predicate.BudgetCheck is not null)
{
    var check = predicate.BudgetCheck;
    Console.WriteLine($"Environment: {check.Environment}");
    Console.WriteLine($"Result: {check.Result}");
    Console.WriteLine($"Total: {check.ActualCounts.Total}/{check.Config.MaxUnknownCount}");
    Console.WriteLine($"Config Hash: {check.ConfigHash}");
}
```

### Verifying Configuration Hash

```csharp
// Compute expected hash from current configuration
var currentConfig = new VerdictBudgetConfig(
    maxUnknownCount: 10,
    maxCumulativeUncertainty: 2.5,
    action: "warn");

var expectedHash = VerdictBudgetCheck.ComputeConfigHash(currentConfig);

// Compare with attested hash
if (predicate.BudgetCheck?.ConfigHash != expectedHash)
{
    Console.WriteLine("Warning: Budget configuration has changed since attestation");
}
```

## Determinism

The config hash ensures reproducibility:

1. Configuration is serialized to JSON with canonical ordering
2. SHA-256 is computed over the UTF-8 bytes
3. Hash is prefixed with `sha256:` algorithm identifier

This allows verification that the same budget configuration was used across runs.

## Integration Points

### VerdictPredicateBuilder

Budget check is added when building verdict predicates:

```csharp
var budgetCheck = new VerdictBudgetCheck(
    environment: context.Environment,
    config: config,
    actualCounts: counts,
    result: budgetResult.Passed ? "pass" : budgetResult.Budget.Action.ToString(),
    configHash: VerdictBudgetCheck.ComputeConfigHash(config),
    evaluatedAt: DateTimeOffset.UtcNow,
    violations: violations);

var predicate = new VerdictPredicate(
    tenantId: trace.TenantId,
    policyId: trace.PolicyId,
    // ... other fields
    budgetCheck: budgetCheck);
```

### UnknownBudgetService

The enhanced `BudgetCheckResult` includes all data needed for attestation:

```csharp
var result = await budgetService.CheckBudget(environment, unknowns);

// result.Budget - the configuration applied
// result.CountsByReason - breakdown for attestation
// result.CumulativeUncertainty - total uncertainty score
```

## Related Documentation

- [Unknown Budget Gates](./unknowns-budget-gates.md)
- [Verdict Attestations](../attestor/verdict-format.md)
- [BudgetCheckPredicate Model](../../api/attestor/budget-check-predicate.md)