# abi-control-core

The foundation contract layer for the ABI ecosystem. Provides 50 locked JSON Schema contracts, an audit trail SDK, and deterministic content fingerprinting (RFC 8785 JCS + SHA-256).

Zero upstream `abi-*` dependencies. This is **Contracts Pack (Layer 1)** -- everything else builds on top of it.

## Install (after PyPI publication)

```bash
pip install abi-control-core
```

> **Status**: Not yet published to PyPI. Install from source: `pip install -e .` from the repo root.

## Quick start

```python
from pathlib import Path
from abi_control_core.sdk.validate import validate_json
from abi_control_core.sdk.evidence_pack import EvidencePackBuilder
from abi_control_core.sdk.canonical_hash import canonical_hash_jcs_sha256

# Validate a payload against a locked schema
validate_json(payload, "artifact_manifest.schema.json")

# Build an audit trail artifact
builder = EvidencePackBuilder(base_dir=Path("evidence_packs"), run_id="run-42")
builder.set_manifest({"name": "my-run", "status": "complete"})
builder.add_artifact(b"raw file contents")  # content-addressed storage
summary = builder.finalize()  # validates, writes hashes, returns summary dict

# Deterministic content fingerprint (RFC 8785 JCS + SHA-256)
digest = canonical_hash_jcs_sha256({"key": "value"})
```

## What's included

- **50 JSON Schema contracts** in `src/abi_control_core/contracts/`, all locked in `contracts.lock.json` with SHA-256 hashes for schema integrity verification
- **Audit trail SDK** -- generate, seal, and validate structured audit trail artifacts
- **Deterministic content fingerprinting** -- RFC 8785 JSON Canonicalization Scheme + SHA-256
- **Pydantic domain models** -- canonical types shared across the ABI ecosystem

### Schema catalog highlights

**Core Control Plane:** audit trail artifacts, artifact manifests, AICS receipts, budget state and receipts, capability boundary registry, context manifests.

**Agent Orchestration:** agent profiles, structured agent-to-agent handoff schemas, routing tables, execution records, session lifecycle, telemetry.

**Quality & Observability:** calibration reports, failure taxonomy, tamper-evident approval log (hash-chained gate execution receipts).

**Evaluation & Regression:** eval case, fixture, and result schemas; regression gate manifests.

## Schema integrity verification

All 50 schemas are locked in `contracts.lock.json` with SHA-256 hashes. Verify nothing has drifted:

```bash
python script/verify.py
```

## ABI ecosystem

`abi-control-core` is the Contracts Pack (Layer 1). Other ABI packages depend on it, but it depends on none of them. Related packages:

- [abi-spec](https://github.com/AbilityBI/abi-spec) -- specification compiler (Layer 2)
- [abi-prd](https://github.com/AbilityBI/abi-prd) -- structured PRD generation (Layer 2)
- [abi-policy](https://github.com/AbilityBI/abi-policy) -- policy evaluation engine
- [abi-evals](https://github.com/AbilityBI/abi-evals) -- eval runner and golden management
- [abi-observability](https://github.com/AbilityBI/abi-observability) -- OTLP-compliant telemetry

## Versioning

Follows Semantic Versioning. Current version: `0.1.4`. See CHANGELOG.md for release notes.

## License

MIT License (see LICENSE file).
