System Architecture
Overview
| Aspect | Details |
|---|---|
| Purpose | Edit-agnostic safety evaluation framework for ML model weight modifications. |
| Audience | Developers extending InvarLock, operators debugging pipelines, security reviewers. |
| Core components | CLI layer, Core runtime, Guard chain, Reporting/report subsystem. |
| Design goals | Torch-independent core, edit-agnostic guards, deterministic evaluation, full provenance. |
| Source of truth | src/invarlock/core/runner.py, src/invarlock/cli/commands/*.py, src/invarlock/guards/*.py. |
See the Glossary for definitions of terms such as the canonical guard chain, policy digest, and measurement contract.
Contents
- Quick Reference
- High-Level Architecture
- Component Layers
- Pipeline Flow
- Guard Chain Architecture
- report Generation Flow
- Key Design Decisions
- Module Dependencies
- Extension Points
- Related Documentation
Quick Reference
┌─────────────────────────────────────────────────────────────────────────────┐
│ INVARLOCK SYSTEM OVERVIEW │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ USER INPUT PROCESSING OUTPUT │
│ ───────── ────────── ────── │
│ │
│ ┌──────────┐ ┌────────────────────────────────┐ ┌──────────────┐ │
│ │ Config │───▶│ CLI LAYER │───▶│ report │ │
│ │ (YAML) │ │ evaluate | run | verify ... │ │ (JSON) │ │
│ └──────────┘ └───────────────┬────────────────┘ └──────────────┘ │
│ │ │
│ ┌──────────┐ ┌───────────────▼────────────────┐ ┌──────────────┐ │
│ │ Model │───▶│ CORE RUNTIME │───▶│ report │ │
│ │ (HF ID) │ │ runner.py + adapters + edits │ │ (JSON) │ │
│ └──────────┘ └───────────────┬────────────────┘ └──────────────┘ │
│ │ │
│ ┌──────────┐ ┌───────────────▼────────────────┐ ┌──────────────┐ │
│ │ Dataset │───▶│ GUARD CHAIN │───▶│ Events │ │
│ │(provider)│ │ inv(pre)→spectral→rmt→var→post │ │ (JSONL) │ │
│ └──────────┘ └────────────────────────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
High-Level Architecture
InvarLock follows a layered architecture with clear separation of concerns:
┌─────────────────────────────────────────────────────────────────────────────┐
│ CLI LAYER │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ evaluate │ │ run │ │ verify │ │ report │ │ doctor │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │ │
├───────┴────────────┴────────────┴────────────┴────────────┴─────────────────┤
│ CORE RUNTIME │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ runner.py │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │
│ │ │prepare │─▶│ guards │─▶│ edit │─▶│ guards │─▶│ eval │ │ │
│ │ │ model │ │(before)│ │ apply │ │(after) │ │ final │ │ │
│ │ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────────┤
│ GUARD LAYER │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ invariants │ │ spectral │ │ rmt │ │ variance │ │
│ │ (integrity)│ │ (weights) │ │(activation)│ │ (A/B) │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
│ │
├─────────────────────────────────────────────────────────────────────────────┤
│ REPORTING LAYER │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ report │ │ report │ │ render │ │ manifest │ │
│ │ (JSON) │ │ (JSON) │ │ (MD/HTML) │ │ (JSON) │ │
│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Component Layers
CLI Layer (src/invarlock/cli/)
Typer-based command-line interface providing user-facing entry points.
| Command | Purpose | Primary Output |
|---|---|---|
evaluate | Compare baseline vs subject with pinned windows | report JSON + MD |
run | Single-model evaluation pipeline | Report JSON + Events JSONL |
verify | Validate report against schema and pairing | Exit code + messages |
report | Render/compare reports and reports | MD/HTML/JSON artifacts |
doctor | Environment diagnostics | Health check output |
plugins | List adapters, guards, edits | Plugin inventory |
Core Runtime (src/invarlock/core/)
Pipeline orchestration without direct torch imports (torch-independent coordination).
| Module | Responsibility |
|---|---|
runner.py | Pipeline phases: prepare → guards → edit → eval → finalize |
api.py | Protocol definitions for ModelAdapter, ModelEdit, Guard |
bootstrap.py | BCa bootstrap CI computation for paired metrics |
checkpoint.py | Snapshot/restore for retry loops |
registry.py | Plugin discovery and registration |
Guard Layer (src/invarlock/guards/)
Four-guard pipeline for edit safety validation.
| Guard | Focus | Key Metric |
|---|---|---|
invariants | Structural integrity, NaN/Inf checks | validation.invariants_pass |
spectral | Weight matrix spectral norm stability | κ-threshold violations |
rmt | Activation edge-risk via Random Matrix Theory | ε-band compliance |
variance | Variance equalization with A/B gate | Predictive gain |
Reporting Layer (src/invarlock/reporting/)
report generation, validation, and rendering.
| Module | Responsibility |
|---|---|
report.py | report schema and validation |
render.py | Markdown report rendering |
html.py | HTML export with styling |
report.py | Report generation and manifest |
telemetry.py | Performance metrics collection |
Pipeline Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ EVALUATION PIPELINE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ PHASE 1: BASELINE RUN │
│ ───────────────────── │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Load │───▶│ Evaluate │───▶│ Record │───▶│ Save │ │
│ │ Model │ │ Windows │ │ Guards │ │ Report │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ PHASE 2: SUBJECT RUN (with baseline window pinning) │
│ ─────────────────────────────────────────────── │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Load │───▶│ Apply │───▶│ Evaluate │───▶│ Record │ │
│ │ Model │ │ Edit │ │ Paired │ │ Guards │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ PHASE 3: EVALUATION REPORT GENERATION │
│ ────────────────────────────────────── │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Pair │───▶│ Compute │───▶│ Apply │───▶│ Render │ │
│ │ Windows │ │ Ratios │ │ Gates │ │ Report │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Guard Chain Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ GUARD CHAIN EXECUTION │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ CANONICAL ORDER: invariants → spectral → rmt → variance → invariants │
│ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ BEFORE EDIT │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ INVARIANTS │ │ SPECTRAL │ │ RMT │ │ │
│ │ │ prepare() │ │ prepare() │ │ prepare() │ │ │
│ │ │ ────────── │ │ ────────── │ │ ────────── │ │ │
│ │ │ • NaN check │ │ • Baseline σ │ │ • Baseline ε │ │ │
│ │ │ • Shape check│ │ • Family caps│ │ • Activation │ │ │
│ │ │ • Tying check│ │ • z-scores │ │ • Calibration│ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ EDIT APPLIED │ │
│ │ (quant_rtn, noop, or external BYOE checkpoint) │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ AFTER EDIT │ │
│ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ INVARIANTS │ │ SPECTRAL │ │ RMT │ │ │
│ │ │ validate() │ │ validate() │ │ validate() │ │ │
│ │ │ ────────── │ │ ────────── │ │ ────────── │ │ │
│ │ │ • Post-edit │ │ • κ-check │ │ • ε-band │ │ │
│ │ │ integrity │ │ • Caps count │ │ compliance │ │ │
│ │ │ • NaN detect │ │ • Stability │ │ • Δ tracking │ │ │
│ │ └──────────────┘ └──────────────┘ └──────────────┘ │ │
│ │ │ │
│ │ ┌──────────────┐ │ │
│ │ │ VARIANCE │ (A/B test: bare vs VE-enabled) │ │
│ │ │ validate() │ │ │
│ │ │ ────────── │ │ │
│ │ │ • Gain check │ │ │
│ │ │ • CI overlap │ │ │
│ │ │ • Enable/skip│ │ │
│ │ └──────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────┐ │
│ │ GUARD RESULTS │ │
│ │ │ │
│ │ • validation.invariants_pass: bool │ │
│ │ • validation.spectral_stable: bool │ │
│ │ • validation.rmt_stable: bool │ │
│ │ • measurement_contract_hash: str (CI/Release verification) │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Report Generation Flow
┌─────────────────────────────────────────────────────────────────────────────┐
│ report GENERATION │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ INPUTS │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Baseline │ │ Subject │ │ Policy │ │ Profile │ │
│ │ report │ │ report │ │ (tiers.yaml)│ │ (ci/release)│ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ └────────────────┴────────────────┴────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ report BUILDER │ │
│ │ 1. Pair baseline/subject windows │ │
│ │ 2. Compute paired ΔlogNLL + BCa bootstrap │ │
│ │ 3. Apply policy gates (PM ratio, drift, guard checks) │ │
│ │ 4. Emit validation flags + state │ │
│ │ 5. Attach provenance (seeds) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ OUTPUTS │
│ ┌────────────────────┐ ┌───────────────────┐ ┌────────────────────┐ │
│ │ evaluation.report │ │ evaluation_report │ │ evaluation.html │ │
│ │ .json │ │ .md │ │ │ │
│ └────────────────────┘ └───────────────────┘ └────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Key Design Decisions
| Decision | Rationale | Implementation |
|---|---|---|
| Torch-independent core | runner.py coordinates without importing torch; adapters encapsulate torch-specific logic. | Adapter protocol in core/api.py |
| Edit-agnostic guards | Guards work with any weight modification (quantization, pruning, LoRA merge). | Guard protocol validates model state, not edit type |
| Tier-based policies | Calibrated thresholds in tiers.yaml for balanced/conservative/aggressive safety profiles. | Policy resolution in guards/policies.py |
| Deterministic evaluation | Seed bundle + window pairing schedules ensure reproducible metrics. | meta.seeds, dataset.windows.stats tracking |
| Plugin architecture | Entry points for guards, adapters, edits enable extension without core changes. | importlib.metadata discovery in core/registry.py |
| Log-space primary metrics | Paired ΔlogNLL with BCa bootstrap avoids ratio math bias. | core/bootstrap.py implementation |
Module Dependencies
┌─────────────────────────────────────────────────────────────────────────────┐
│ MODULE DEPENDENCY GRAPH │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ │
│ │ CLI │ │
│ │ commands/* │ │
│ └──────┬──────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ core/ │ │ guards/ │ │ reporting/ │ │
│ │ runner.py │───▶│ *.py │───▶│ *.py │ │
│ └──────┬──────┘ └──────┬──────┘ └─────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ adapters/ │ │ edits/ │ │
│ │ hf_*.py │ │ quant_rtn.py│ │
│ └──────┬──────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────┐ │
│ │ eval/ │ (metrics, datasets, tasks) │
│ │ *.py │ │
│ └─────────────┘ │
│ │
│ KEY: ───▶ imports/depends on │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Extension Points
InvarLock supports extension via entry points without modifying core code.
| Extension Type | Entry Point Group | Example |
|---|---|---|
| Adapters | invarlock.adapters | hf_causal, hf_mlm, hf_causal |
| Guards | invarlock.guards | invariants, spectral, rmt, variance |
| Edits | invarlock.edits | quant_rtn, noop |
Custom Adapter Example
# my_adapter.py
from invarlock.core.api import ModelAdapter
class MyAdapter(ModelAdapter):
name = "my_custom_adapter"
def load(self, model_id: str, device: str) -> nn.Module:
# Custom loading logic
...
def describe(self, model: nn.Module) -> dict:
# Return model metadata
...
# pyproject.toml
[project.entry-points."invarlock.adapters"]
my_custom_adapter = "my_adapter:MyAdapter"
Troubleshooting
- Import errors in torch-free context: ensure
invarlock.coreimports stay torch-independent; use adapters for torch operations. - Guard preparation failures: check tier policy compatibility; use
context.run.strict_guard_prepare: falsefor debugging. - report generation errors: verify baseline and subject reports exist and have compatible window structures.
Observability
- Pipeline phases emit timing via
print_timing_summary()in CLI. - Guard results recorded in
report.guards[]and reportvalidation.*flags. - Telemetry fields include
memory_mb_peak,latency_ms_*,duration_s.
Related Documentation
- CLI Reference — Command usage and options
- Guards Reference — Guard configuration and evidence
- Configuration Schema — YAML config structure
- reports — report schema and verification
- Assurance Case Overview — Assurance claims and evidence