# AGENTS.md

## Architecture

This repository implements `KappaBridge` as a Python package under `src/idea156_kappabridge_privacy_safe`.

Core modules:
- `contracts.py`: canonical contract models for `Object`, `SharedSignal`, `PlanDelta`, `DatasetSchema`, `AccessPolicy`, and audit/reproducibility records.
- `storage.py`: SQLite persistence with SQLAlchemy, including the contract table and tamper-evident governance ledger.
- `registry.py`: graph-of-contracts registry backed by `networkx`.
- `attestation.py`: Ed25519-based cryptographic attestations for contract use.
- `sync.py`: deterministic delta sync envelopes for offline-first reconnection.
- `adapters.py`: lab/data-format adapters for climate, epidemiology, genomics, ecology, and image datasets.
- `optimizer.py`: lightweight deterministic federated planner for joint experiment requests.
- `harness.py`: conformance harness for adapter validation.

## Tech Stack

- Python 3.11+
- Pydantic for contract validation
- SQLAlchemy + SQLite for durable persistence
- Cryptography for attestations
- NetworkX for the contract graph
- Pandas, Pillow, and NumPy for adapter support

## Testing

- Run `bash test.sh` to build the package and execute the full test suite.
- The script must continue to pass after any change to contracts, ledger hashing, or sync behavior.

## Rules

- Keep contract hashing canonical and deterministic.
- Do not mutate stored contracts; append new records instead.
- Preserve ledger ordering and hash chaining.
- When adding adapters, ensure they produce stable, validated manifests.
- Prefer the smallest correct change that keeps offline sync and governance auditable.