# BuildLedger Agent Guide

## Architecture

- `buildledger.models` defines the canonical provenance objects.
- `buildledger.ledger` stores immutable entries in SQLite and verifies chain integrity.
- `buildledger.schemas` provides a versioned schema registry over the core models.
- `buildledger.sync` emits and applies delta packets for reconnect/resync workflows.
- `buildledger.anchors` records tamper-evident head anchors.
- `buildledger.adapters` normalizes CI context into build contracts.
- `buildledger.cli` offers small operational commands for local use.

## Tech Stack

- Python 3.11+
- `pydantic` for strict model validation
- `sqlite3` for local persistence
- `pytest` for tests
- `build` for packaging verification

## Testing

- Run `bash test.sh` from the repo root.
- `test.sh` must succeed with `pytest` and `python3 -m build`.

## Rules

- Keep ledger records append-only and hash-verified.
- Prefer canonical JSON serialization for hashes and sync packets.
- Keep adapters thin and deterministic.
- Add or update tests when changing model, storage, or sync logic.
- Preserve ASCII unless a file already requires otherwise.