cosmosmesh-privacy-preserving-federated-/AGENTS.md

CosmosMesh Privacy-Preserving Federated Mission Planning

Architecture overview

• Language: Python for MVP scaffolding (scaffold only)
• Core package: cosmosmesh_privacy_preserving_federated_
• Tests: pytest-driven in tests/ directory
• Build: Python packaging with pyproject.toml using setuptools

How to contribute

• Run tests with ./test.sh
• Package name and version are defined in pyproject.toml
• README describes how to extend the MVP and plug in adapters

Testing commands

• Build the project: python3 -m build
• Run tests: pytest -q
• Run the complete test script: bash test.sh

Rules

• Do not modify public API semantics for MVP scaffolding unless asked
• Focus on small, correct changes and clear documentation

CosmosMesh CatOpt bridge (MVP)

• We are prototyping a lightweight interoperability bridge that maps CosmosMesh MVP primitives to a CatOpt-style representation (Objects/ Morphisms/ Functors) to enable cross-domain experimentation without heavy dependencies.
• Starter adapters: rover and habitat module adapters exposing simple interfaces for readState, exposeLocalProblemData, and applyCommand.
• Transport: TLS-based, e.g., MQTT/REST for prototyping.
• Deliverables: a minimal CatOpt bridge module (src/cosmosmesh_privacy_preserving_federated/catopt_bridge.py), a small registry graph for contracts, and a DSL sketch to describe LocalProblem/SharedVariables/DualVariables/PlanDelta. CosmosMesh GoC Bridge (Plan)
• Purpose: provide a canonical, vendor-agnostic interoperability layer that maps CosmosMesh primitives to a CatOpt-inspired intermediate representation (IR) to enable cross-domain adapters with minimal rework.
• Core concepts:
  • Objects -> LocalProblems (per-asset planning state)
  • Morphisms -> SharedVariables / DualVariables (versioned summaries, priors)
  • PlanDelta -> incremental plan changes with cryptographic tags
  • TimeMonoid / Metadata -> per-message timing, nonce, signatures for replay protection
  • Graph-of-Contracts registry -> versioned data schemas and adapter conformance harness
• MVP wiring (8–12 weeks, 2–3 agents to start):
  1. Phase 0: protocol skeleton + 2 starter adapters (rover_planner, habitat_module) with TLS transport; lightweight ADMM-lite local solver; delta-sync with deterministic replay on reconnects;
  2. Phase 1: governance ledger scaffold; identity layer (DID/short-lived certs); secure aggregation for SharedVariables; adapter conformance tests.
  3. Phase 2: cross-domain demo in a simulated second domain; publish a CosmosMesh SDK and a canonical transport; toy contract examples and adapters.
  4. Phase 3: hardware-in-the-loop validation with Gazebo/ROS for 2–3 devices; KPI dashboards for convergence speed, delta-sync latency, auditability.
• Deliverables to align with repo: add a minimal goC_bridge.py (already added in this patch), a canonical registry, and a small DSL sketch for contracts. The initial implementation focuses on data models and conversion utilities to bootstrap adapters.
• Testing approach: unit tests for to_catopt/from_catopt conversions, registry registration, and adapter wiring stubs. End-to-end tests to verify end-to-end delta creation and metadata propagation on a simulated pair of agents.
• Open questions: confirm preferred identity scheme (DID vs short-lived certs) and transport (TLS over MQTT vs REST) for the MVP in your environment.