build(agent): new-agents-2#7e3bbc iteration

AGENTS.md

@@ -15,6 +15,13 @@ What to expect in this sprint
 - 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.

arbsphere/two_venue_demo.py

@@ -48,6 +48,45 @@ def run_demo() -> None:
     print("Venue-2 execution history:", broker_b.history())
 
 
+def build_toy_mvp() -> dict:
+    """Bootstrap a minimal, test-friendly two-venue MVP scaffold.
+
+    Returns a lightweight description of the MVP wiring, useful for tests
+    or quick bootstrapping without running the full demo.
+    """
+    # Define two toy LocalArbProblems
+    lp1 = LocalArbProblem(asset_pair=("AAPL", "MSFT"), target_mispricing=0.5, liquidity_budget=1000.0, latency_budget=5.0)
+    lp2 = LocalArbProblem(asset_pair=("GOOG", "AMZN"), target_mispricing=0.7, liquidity_budget=800.0, latency_budget=6.0)
+
+    shared = SharedSignals(
+        deltas=[0.1, -0.05],
+        cross_venue_corr=0.25,
+        liquidity_availability={"venue-1": 0.8, "venue-2": 0.75},
+        latency_proxy=0.9,
+    )
+
+    delta = admm_lite_step([lp1, lp2], shared)
+
+    # Lightweight descriptor of the MVP wiring for external tooling
+    return {
+        "lp_pairs": [
+            {"asset_pair": lp1.asset_pair, "target_mispricing": lp1.target_mispricing, "liquidity_budget": lp1.liquidity_budget, "latency_budget": lp1.latency_budget},
+            {"asset_pair": lp2.asset_pair, "target_mispricing": lp2.target_mispricing, "liquidity_budget": lp2.liquidity_budget, "latency_budget": lp2.latency_budget},
+        ],
+        "shared_signals": {
+            "deltas": list(shared.deltas),
+            "cross_venue_corr": shared.cross_venue_corr,
+            "liquidity_availability": dict(shared.liquidity_availability),
+            "latency_proxy": shared.latency_proxy,
+        },
+        "plan_delta": {
+            "legs": delta.legs,
+            "total_size": delta.total_size,
+            "delta_id": delta.delta_id,
+            "timestamp": delta.timestamp,
+        },
+    }
+
 def main() -> None:
     print("Starting ArbSphere two-venue demo...")
     run_demo()

docs/arbsphere_mvp_toy_spec.md

@@ -0,0 +1,38 @@
+# ArbSphere Toy MVP: Two-Venue Federated Cross-Exchange Arb
+
+Overview
+- A lightweight, privacy-preserving, two-venue MVP to demonstrate canonical ArbSphere primitives and federated coordination.
+- Primitives used:
+  - LocalArbProblem: per-venue task defining asset_pair, target_mispricing, liquidity budget, latency budget
+  - SharedSignals: aggregated price deltas, cross-venue correlations, liquidity proxies, latency proxies
+  - PlanDelta: incremental hedge actions with legs, sizes, and timing
+  - DualVariables, PrivacyBudget, AuditLog: governance and provenance hooks for later phases
+
+Canonical IR mapping
+- EnergiBridge (vendor-agnostic IR) maps primitives to a stable, versioned IR that adapters can consume.
+- Phase 0 MVP uses a minimal IR shape:
+  - Object: LocalArbProblem
+  - SharedSignals
+  - PlanDelta (optional)
+
+Two-venue MVP surface
+- Data-feed adapter: streams quotes and order-book depth from venue A and B (toy data for MVP).
+- Execution adapter: aggregates legs and routes orders across venues with per-order metadata.
+- Lightweight ADMM-lite coordinator at the edge/regional node coordinates local tasks and shares only aggregated signals.
+
+Data contracts seeds (seed artifacts)
+- LocalArbProblem, SharedSignals, PlanDelta, DualVariables, PrivacyBudget, AuditLog, TimeRounds
+- Graph-of-Contracts (GoC) registry for adapter metadata, versioning, and compatibility checks
+
+MVP milestones (8–12 weeks)
+- Phase 0: protocol skeleton + 2 adapters over TLS; deterministic delta-sync; toy cross-venue hedge.
+- Phase 1: governance ledger scaffold; DID/short-lived certs; secure aggregation defaults.
+- Phase 2: cross-domain demo in a simulated two-venue environment; ArbSphere SDK; reference transport.
+- Phase 3: latency tests; KPI dashboards for convergence, delta-merge latency, and auditability.
+
+Open questions
+- Do we start with two venues using synthetic feeds, then scale to live pilots?
+- What is the minimum EnergiBridge surface and per-message metadata needed for plug-and-play adapters?
+
+Notes
+- This document intentionally stays lightweight and extensible to avoid premature optimization.