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 covers GPT-2 and BERT profiles. Repo-included presets and pilot configs for families such as Mistral 7B, Qwen2 7B, Qwen2.5 7B, and Qwen2.5 14B expand runnable coverage, not the published assurance basis.

Guard Pipeline Flow

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, alongside required runtime.manifest.json runtime provenance for evaluation outputs.

Guard hooks

Verify gate requirements

Reference

Guard summary

Guard evidence matrix

Invariants Guard

guards:
  invariants:
    strict_mode: false
    on_fail: monitor   # monitor | rollback | block

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