AidMesh – Architecture & Agent Protocols

- Goal: A privacy-preserving, offline-first disaster-relief orchestration framework that federates local planning using a canonical contract model.
- Core concepts (GoC): LocalProblem (Objects), SharedSignals / DualVariables (Morphisms), PlanDelta, AuditLog, PrivacyBudget, and Time Rounds for delta-sync.
- Tech Stack (production-ready): Python 3.8+, FastAPI optional, SQLite or in-memory storage, cryptographic tagging for messages, and a lightweight ADMM-lite solver for cross-organization coordination.

- Repository structure:
  - src/idea151_aidmesh_federated_privacy/: package
  - tests/: unit tests for core primitives
  - AGENTS.md: this file
  - README.md: product overview and how to contribute

- Testing & tooling:
  - test.sh: runs pytest, builds the package to verify packaging metadata.
  - The build step uses python3 -m build and stores artifacts in dist/.

- Conventions:
  - Use dataclasses for data models. Immutable where possible.
  - Keep adapters pluggable via small interface; adapters communicate via TLS-like envelopes (simulated in tests).
  - Deterministic replay: delta logs can be replayed; no non-deterministic dependencies in tests.

- Collaboration model:
  - Phase-based rollout as described in the MVP blueprint.
  - Adapters (starter set): SupplyDepotController, FieldDistributionPlanner.

- Governance & privacy:
  - Per-message crypto-tags, tamper-evident logs, optional differential privacy budgets, and short-lived identities.

- Tests & quality gates:
  - At least one basic test in tests/ ensuring core primitives function end-to-end.
  - test.sh should succeed, including a packaging build check.