# Architecture

## High-Level Design
Canonical contracts, evidence packs, and validation SDK for the AbilityBI control plane.

## Components
- src/abi_control_core/ — canonical contracts and SDK
- src/abi_control_core/contracts/ — shared schema definitions
- tests/ — unit and integration tests

## Interfaces
Inputs: Structured data, policy definitions, or API requests depending on module.
Outputs: Processed results, evidence packs, or structured reports.

## Improvement Maturity Model
This repository supports the ABI Improvement Maturity Model, progressing from manual iteration (Level 1) through offline eval suites (Level 2) toward observability-driven improvement (Level 3+).

Key architectural components supporting improvement maturity:
- **contracts.lock.json** — locked schema hashes for tamper detection and contract stability
- **calibration_report.schema.json** — structured calibration metrics per run
- **failure_taxonomy.schema.json** — classified failure types for observability
- **gate_ledger.schema.json** — hash-chained gate execution receipts for governance

See [IMPROVEMENT_MATURITY.md](IMPROVEMENT_MATURITY.md) for the full maturity progression and architectural principles.
