System Architecture

Overview

See the Glossary for definitions of terms such as the canonical guard chain, policy digest, and measurement contract.

Contents

1. Quick Reference
2. High-Level Architecture
3. Component Layers
4. Pipeline Flow
5. Guard Chain Architecture
6. Report Generation Flow
7. Architecture Guardrails
8. Key Design Decisions
9. Module Dependencies
10. Extension Points
11. Related Documentation

Quick Reference

High-Level Architecture

InvarLock follows a layered architecture with clear separation of concerns:

Component Layers

CLI Layer (src/invarlock/cli/)

Typer-based command shells providing user-facing entry points. The command modules should stay thin: parse arguments, call core/reporting owners, render output, and map failures to exit codes.

Shell support modules such as cli/config_execution.py, cli/run_execution.py, cli/run_config.py, cli/run_pairing.py, cli/run_overhead.py, and cli/run_artifacts.py belong to this boundary layer as well. They can perform CLI-facing adaptation and console/event rendering, but they must not become policy owners.

Core Policy / Contracts (src/invarlock/core/, src/invarlock/reporting/)

Deterministic policy, artifact-contract, and report-verification owners shared by the CLI and non-CLI entrypoints.

Runtime Provenance Verification Ownership

Runtime provenance uses a single verifier implementation:

• core/runtime_manifest_verify.py is the authoritative verifier for runtime.manifest.json plus report-digest binding checks.
• runtime_verify.py and cli/runtime_verify.py are the programmatic and CLI entrypoints for that verifier.
• runtime_provenance.py calls the same verifier when invarlock verify enforces runtime provenance on container-backed reports.
• Product behavior does not depend on finding an external verifier binary on PATH; verifier semantics are package-native and deterministic across installs.

Core Runtime (src/invarlock/core/)

Pipeline orchestration without direct torch imports (torch-independent coordination).

Guard Layer (src/invarlock/guards/)

Four-guard pipeline for edit safety validation.

Reporting Layer (src/invarlock/reporting/)

Report generation, validation, persistence, and rendering.

Pipeline Flow

Guard Chain Architecture

Report Generation Flow

Architecture Guardrails

The shell/core split is enforced by design and by targeted architecture guard tests. The intended invariants are:

• No lazy exports in package roots such as adapters/__init__.py or guards/__init__.py. Package roots should expose only explicit canonical exports.
• No rmt_legacy references in production source. RMT ownership lives in rmt.py, rmt_analysis.py, rmt_detection.py, and rmt_math.py.
• No dependency-map orchestration in command shells. Public command owners must stay thin and must not rebuild giant deps dictionaries or inject callables to recreate removed indirection.
• No compatibility-only command signatures once a canonical owner contract exists. Example: lens-metric calculation takes a required MetricsConfig instead of deprecated per-call overrides.
• No CLI imports inside owner layers. Modules under src/invarlock/core/ and src/invarlock/reporting/ must stay callable without importing invarlock.cli.

These guardrails keep the CLI as an imperative shell while policy, contracts, and verdict computation remain reusable from non-CLI flows such as evidence-pack verification and programmatic execution.

Key Design Decisions

Module Dependencies

Extension Points

InvarLock supports extension via entry points without modifying core code.

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.core imports stay torch-independent; use adapters for torch operations.
• Guard preparation failures: check tier policy compatibility; use context.run.strict_guard_prepare: false for 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 report validation.* 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