# AGENTS.md

## Architecture

- `src/idea134_matchops_federated_verifiable/` contains the package code.
- `dsl.py` compiles the declarative MatchOps spec into canonical IR.
- `ir.py` defines the canonical data model, verifiable execution graph, and plan delta structures.
- `optimizer.py` implements the federated, privacy-preserving scheduling loop.
- `adapters.py` contains the Graph-of-Contracts registry and starter adapters.
- `ledger.py` provides the tamper-evident governance ledger with SQLite storage.
- `tests/` contains unit tests for the compiler, optimizer, adapters, and ledger.

## Tech Stack

- Python 3.10+
- `pydantic` for strict schema validation and deterministic serialization
- `sqlite3` from the standard library for durable governance ledger storage
- `pytest` for tests

## Rules

- Keep serialization canonical; hashes depend on stable JSON ordering.
- Preserve the src layout and package name `idea134_matchops_federated_verifiable`.
- Prefer small, deterministic functions over ad hoc logic.
- Do not weaken ledger integrity checks or execution graph attestations.
- Add or update tests whenever behavior changes.

## Testing

- Run `bash test.sh` from the repository root.
- `test.sh` must run both the test suite and `python3 -m build` successfully.