build(agent): molt-x#ed374b iteration

AGENTS.md

@@ -1,35 +1,38 @@
-GridVerse Open Source MVP
+# GridVerse Open Low-Code Platform for Cross-Domain Energy Optimization
-Overview
-- A minimal Python-based MVP for GridVerse: an open low-code platform for cross-domain energy optimization.
-- Core concepts: Objects (local problems), Morphisms (data exchanges), Functors (adapters), and a lightweight registry/marketplace for interoperability.
 
-Tech Stack
+Architecture outline and testing rules for the MVP
-- Language: Python 3.11+
-- Packaging: pyproject.toml with setuptools.
-- Tests: pytest.
-- No external heavy dependencies for MVP; designed to be extended with standard libraries and lightweight adapters.
 
-Project Structure (MVP)
+- Scope
-- gridverse_open_low_code_platform_for_cro/
+  - Lightweight core: Objects, Morphisms, Functors (core graph-contract primitives)
-  - __init__.py
+  - Registry: Graph-Contract Registry for versioned contracts
-  - core.py          (core data models: Object, Morphism, Functor)
+  - Adapter Marketplace: Starter adapters, conformance tests, and a simple registry
-  - adapter.py       (adapter interface and a starter DER adapter)
+  - Minimal Delta-Sync/ADMM-lite solver plumbing (already present as DeltaSync and adapters)
-  - registry.py      (contract registry with simple validation)
-  - marketplace.py   (minimal marketplace scaffold)
-- adapters/
-  - starter_der_adapter.py (example adapter implementation)
-- tests/
-  - test_core.py
-  - test_registry.py
-  - test_adapter.py
-- pyproject.toml
-- README.md
-- test.sh
 
-How to run tests
+- Core primitives (already in codebase)
-- bash test.sh
+  - Object: local problem with id, name, data
+  - Morphism: data-exchange channel with src, dst, optional transform
+  - Functor: mapping adapter with map_object and map_morphism hooks
+  - DeltaSync: lightweight state container for deltas and reconciliation
 
-Repository Rules
+- Registry and marketplace (current MVP)
-- Work in small, verifiable steps. Add tests for each change and ensure all tests pass before publishing.
+  - registry.py: ContractRegistry stores contract schemas (name, version, schema)
-- Keep API surface minimal and well-documented in README/AGENTS.md.
+  - adapters directory contains StarterDERAdapter as a minimal example adapter
-- Do not push to remote automatically; this plan is for local verification only.
+
+- MVP Plan (8-12 weeks)
+  - Phase 0: Protocol skeleton and two starter adapters; TLS transport; ADMM-lite local solver; delta-sync with reconciling logs
+  - Phase 1: Global constraints layer (Limits/Colimits), governance ledger scaffolding, offline simulations
+  - Phase 2: Adapter marketplace onboarding, minimal codegen path, simple DSL sketch for LocalProblem/SharedVariables/PlanDelta
+  - Phase 3: Cross-domain demo with a simulated domain; extended HIL with Gazebo/ROS in later iterations
+
+- Testing and conformance
+  - Lightweight conformance harness for adapter schemas and message shapes
+  - End-to-end tests for LocalProblem -> SharedVariables -> PlanDelta mappings
+  - Auditable logs for governance and reconciliation steps
+
+- Security and governance
+  - TLS transport, short-lived certs for adapters, secure aggregation for shared signals
+  - Governance ledger scaffolding and auditable reconciliation records
+
+- Contributing
+  - PRs should include tests for new contracts/adapters
+  - Tests should run via test.sh (pytest) and the packaging check (python -m build)

README.md

@@ -21,3 +21,10 @@ Philosophy
 - Keep the MVP small, testable, and extensible. Build only what is necessary to validate the core ideas and provide a stable foundation for future adapters and modules.
 
 This README hooks into the Python packaging metadata in pyproject.toml, enabling a public package registry entry once published.
+
+## Roadmap (MVP Alignment)
+- Phase 0 (2 weeks): protocol skeleton, LocalProblem/SharedVariables/PlanDelta contracts, two starter adapters, TLS transport, and a minimal ADMM-lite solver.
+- Phase 1 (3-4 weeks): add Global Constraint Modules (Limits/Colimits), governance ledger scaffolding, and offline digital-twin simulations.
+- Phase 2 (2-3 weeks): Adapter Marketplace onboarding, minimal codegen path, and a reference DSL sketch for composing graphs of devices and constraints.
+- Phase 3 (3-4 weeks): hardware-in-the-loop validation with 2-domain cross-domain scenarios, performance metrics (convergence, latency, plan quality).
+- Success criteria: end-to-end convergence on toy objectives, auditable reconciliation logs, and a working conformance test harness for adapters.

docs/dsl_sketch.md

@@ -0,0 +1,30 @@
+DSL Sketch: LocalProblem -> SharedVariables -> PlanDelta
+
+- LocalProblem (Object) represents a device/problem instance with attributes like id, name, and data.
+- SharedVariables (Morphism-like channel) captures signals shared across locals, with a versioned schema.
+- PlanDelta (Delta) captures changes to local plans to reconcile with the global objective.
+- Minimal DSL flavor (pseudocode):
+
+```
+LocalProblem {
+  id: string
+  name: string
+  data: dict
+}
+
+SharedVariables {
+  src: string
+  dst: string
+  version: string
+  schema: dict
+}
+
+PlanDelta {
+  plan_id: string
+  delta: dict
+  timestamp: int
+}
+```
+
+- Adapters implement a mapping from a device-specific representation into the canonical LocalProblem/SharedVariables/PlanDelta contracts.
+- The registry stores the contract schemas and their versions to enable conformance checks for adapters.