# AGENTS

- This repository contains a lightweight, test-driven Python prototype for ArbSphere's federated cross-arbitrage primitives.
- Core concepts provided: LocalArbProblem, SharedSignals, and a deterministic admm_step that outputs a PlanDelta.
- Tests verify deterministic plan generation and basic structure.
- How to run:
  - bash test.sh
- Important: This document is a stub for onboarding agents and does not describe a full production architecture.

What to expect in this sprint
- MVP mapping: canonical ArbSphere primitives (LocalArbProblem, SharedSignals, PlanDelta) and a minimal EnergiBridge translator to a vendor-agnostic IR.
- A Graph-of-Contracts registry (GoC) to describe adapters and data schemas with per-message metadata for replay protection.
- Deterministic replay: a CRDT-inspired delta structure to enable replay across reconnects.
- A two-venue toy MVP to bootstrap interoperability, including data-feed and broker adapters.
- Phase-wise rollout: protocol skeleton, governance ledger scaffolding, cross-domain demo, and latency/auditability dashboards.
- Compliance and audit: tamper-evident governance logs and optional cross-firm attestations.

Open MVP tasks (tracked):
- Add toy MVP spec doc (docs/arbsphere_mvp_toy_spec.md) – done.
- Expose a lightweight MVP bootstrap helper (arbsphere/two_venue_demo.py -> build_toy_mvp) – done.
- Extend GoC registry with simple adapter metadata examples for two-venue MVP – lightweight scaffolding present in go_registry.py.
- Wire EnergiBridge canonical IR mappings in a minimal two-venue loop (done in arbsphere/energi_bridge.py).
- Prepare a README or docs entry describing how to run the MVP locally and how adapters plug in – in docs and top-level README.

Implementation guidance
- Prefer to implement small, correct changes that improve interoperability and testability.
- Extend EnergiBridge with additional IR fields and versioning as new adapters are added.
- Keep the GoC registry lightweight; avoid coupling adapters to internal Python types.
- Ensure tests remain deterministic and fast.

If you want me to push a concrete two-venue toy MVP spec or add toy adapters, I can draft and implement those next.
- ArbSphere MVP scaffold (Python) OpenPR
- What changed: added core primitives, EnergiBridge skeleton, toy adapters, and tests to enable cross-venue interoperability with auditable replay.
- How to run tests: bash test.sh
- Notes: This is a safe, incremental MVP that lays the groundwork for Phase 0 protocol skeleton and adapters.