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 is the set of published_basis rows in contracts/support_matrix.json, with the readable grouping in docs/README.md#support-matrix. Modern published-basis no-op reports are included as null-behavior guard evidence, but transferred attention caps are budgeted sentinels until family-specific calibration re-derives κ. The strongest public guard-value evidence is the Mistral 7B scenario package under public_evidence/published_basis/mistral_7b/guard_value_demo/: PM-only accepts the selected edits while clean confirmation reruns record baseline-relative spectral, RMT, and variance/VE movement. Invariants remain structural checks in that package and are required to pass. Additional runnable but unpublished lanes are tracked in contracts/support_matrix.json; they 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 packaged 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).
• Reports may include guard_warnings. These are baseline-relative guard-signal changes that still pass the hard policy, such as a new capped spectral module while caps_applied <= max_caps. They are advisory by default and become verification failures only with invarlock verify --fail-on-warnings.
• Evidence packs use the same guard observations but apply stricter scenario semantics. A public guard-value claim requires reproduced baseline-relative scenario evidence; an ordinary warning alone is not enough.

Related Documentation

• Tier Policy Catalog
• GPU/MPS-First Guard Measurement Contracts
• Configuration Schema
• Environment Variables
• Guard Contracts & Primer