Guards

Overview

See the Glossary for definitions of guard terms such as kappa threshold, epsilon band, and guard overhead.

Quick Start

guards:
  order: ["invariants", "spectral", "rmt", "variance", "invariants"]
  spectral:
    sigma_quantile: 0.95
    deadband: 0.10
    scope: ffn
  rmt:
    epsilon_by_family: { ffn: 0.01, attn: 0.01, embed: 0.01, other: 0.01 }
  variance:
    min_gain: 0.0
    scope: ffn

Most thresholds come from the tier defaults (see tiers.yaml). Use overrides sparingly and keep evidence in the report.

Assurance scope note: the published assurance basis currently covers GPT-2 and BERT profiles. Repo-shipped presets and pilot configs for families such as Mistral 7B and Qwen2 7B expand runnable coverage, not the published assurance basis.

Guard Pipeline Flow

┌─────────────────────────────────────────────────────────────────────────┐
│                        GUARD PIPELINE FLOW                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐          │
│   │invariants│───▶│ spectral │───▶│   rmt    │───▶│ variance │          │
│   │(pre-edit)│    │ (weight) │    │(activatn)│    │  (A/B)   │          │
│   └────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘          │
│        │               │               │               │                │
│        ▼               ▼               ▼               ▼                │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐          │
│   │ prepare  │    │ prepare  │    │ prepare  │    │ prepare  │          │
│   │(baseline)│    │(baseline)│    │(calibrtn)│    │(calibrtn)│          │
│   └────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘          │
│        │               │               │               │                │
│        ▼               ▼               ▼               ▼                │
│   ┌──────────────────────────────────────────────────────────┐          │
│   │                    EDIT APPLIED                          │          │
│   └──────────────────────────────────────────────────────────┘          │
│        │               │               │               │                │
│        ▼               ▼               ▼               ▼                │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐          │
│   │ validate │    │ validate │    │ validate │    │ validate │          │
│   │(post-edt)│    │(κ-check) │    │(ε-band)  │    │(gain>0?) │          │
│   └────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘          │
│        │               │               │               │                │
│        ▼               ▼               ▼               ▼                │
│   ┌──────────────────────────────────────────────────────────┐          │
│   │                GUARD RESULTS → report                    │          │
│   │     (passed/warned/failed + metrics + measurement_hash)  │          │
│   └──────────────────────────────────────────────────────────┘          │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Concepts

• Guard lifecycle: the core runner calls prepare(...) (if implemented) and always calls validate(...). Optional hooks (before_edit, after_edit, finalize) are only used when you manage guards manually (e.g., with GuardChain).
• Tier policies: --tier balanced|conservative|aggressive resolves a full policy bundle from runtime/tiers.yaml; overrides in config are merged on top.
• Measurement contracts: Spectral and RMT guards record estimator + sampling contracts in reports and are enforced by invarlock verify in CI/Release.

Guard hooks

Verify gate requirements

Reference

Guard summary

Guard evidence matrix

Invariants Guard

guards:
  invariants:
    strict_mode: false
    on_fail: warn   # warn | rollback | abort

Spectral Guard (measurement contract)

guards:
  spectral:
    sigma_quantile: 0.95
    deadband: 0.10
    scope: all
    family_caps: { ffn: 3.85, attn: 3.02, embed: 1.05, other: 0.0 }
    estimator: { iters: 4, init: ones }
    degeneracy:
      enabled: true
      stable_rank: { warn_ratio: 0.5, fatal_ratio: 0.25 }
      norm_collapse: { warn_ratio: 0.25, fatal_ratio: 0.10 }

RMT Guard (activation edge-risk)

guards:
  rmt:
    epsilon_by_family: { ffn: 0.01, attn: 0.01, embed: 0.01, other: 0.01 }
    epsilon_default: 0.01
    estimator: { iters: 3, init: ones }
    activation:
      sampling:
        windows: { count: 8, indices_policy: evenly_spaced }

Variance Guard (A/B gate)

guards:
  variance:
    scope: ffn
    min_gain: 0.0
    min_effect_lognll: 0.0
    max_calib: 200
    clamp: [0.85, 1.12]
    deadband: 0.02
    predictive_gate: true
    predictive_one_sided: false
    calibration:
      windows: 200
      min_coverage: 50
      seed: 123

Guard order

guards.order defines the execution chain and is required in YAML presets. The packaged presets include it by default; remove a guard from the list to skip it.

Troubleshooting

• Guard prepare failed: set context.run.strict_guard_prepare: false in your run config for local debugging, or adjust tier policies for the guard that failed.
• Spectral instability: lower sigma_quantile, narrow scope, or increase deadband to reduce noise.
• RMT ε-band violations: tighten calibration (more windows) or adjust epsilon_by_family only if you are updating tier policy evidence.
• Variance guard never enables: A/B gate may fail; inspect variance.metrics.predictive_gate and variance.metrics.ab_gain in the report.

Observability

• report.guards contains guard results by name.
• reports include resolved_policy.{spectral,rmt,variance} and evidence blocks (spectral.*, rmt.*, variance.*).
• Validation flags are recorded under validation.* (invariants_pass, spectral_stable, rmt_stable).

Related Documentation

• Tier Policy Catalog
• GPU/MPS-First Guards (Decision Memo)
• Configuration Schema
• Environment Variables
• Guard Contracts & Primer