From a355ee528d4363a4a17efdf496b1e8a4d5c08707 Mon Sep 17 00:00:00 2001
From: agent-dd492b85242a98c5 <agent-dd492b85242a98c5@gridmolt.local>
Date: Mon, 20 Apr 2026 15:08:22 +0200
Subject: [PATCH] build(agent): new-agents-3#dd492b iteration

---
 arbsphere/contract_seed.py      | 54 +++++++++++++++++++++++
 docs/arbsphere_mvp_contracts.md | 76 +++++++++++++++++++++++++++++++++
 2 files changed, 130 insertions(+)
 create mode 100644 arbsphere/contract_seed.py
 create mode 100644 docs/arbsphere_mvp_contracts.md

diff --git a/arbsphere/contract_seed.py b/arbsphere/contract_seed.py
new file mode 100644
index 0000000..5e368c4
--- /dev/null
+++ b/arbsphere/contract_seed.py
@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+"""Toy contract seeds for ArbSphere MVP wiring.
+
+This module provides a small, self-contained example of seed payloads that
+can be used by adapters to bootstrap interoperability with the canonical IR
+mapping. It is intentionally lightweight and deterministic.
+"""
+
+from arbsphere.primitives import LocalArbProblem, SharedSignals, DualVariables, AuditLog, PrivacyBudget, AuditLogEntry
+from arbsphere.coordinator import admm_lite_step
+
+
+
+def make_seed_local_arb_problem() -> LocalArbProblem:
+    return LocalArbProblem(
+        asset_pair=("AAPL", "MSFT"),
+        target_mispricing=0.5,
+        liquidity_budget=10000.0,
+        latency_budget=50,
+        id="seed-venue-A-1",
+        venue="venue-A",
+    )
+
+
+def make_seed_shared_signals() -> SharedSignals:
+    return SharedSignals(
+        deltas=[0.1, -0.05],
+        cross_venue_corr=0.75,
+        liquidity_availability={"venue-A": 10000.0, "venue-B": 8000.0},
+        latency_proxy=0.8,
+    )
+
+
+def make_seed_plan_delta(lp_list=None, signals=None) -> dict:
+    if lp_list is None:
+        lp_list = [make_seed_local_arb_problem()]
+    if signals is None:
+        signals = make_seed_shared_signals()
+    delta = admm_lite_step(lp_list, signals)
+    # In arbsphere.coordinator, PlanDelta.timestamp is a float (UNIX time).
+    return {
+        "legs": delta.legs,
+        "total_size": delta.total_size,
+        "delta_id": delta.delta_id,
+        "timestamp": delta.timestamp,
+    }
+
+
+__all__ = [
+    "make_seed_local_arb_problem",
+    "make_seed_shared_signals",
+    "make_seed_plan_delta",
+]
diff --git a/docs/arbsphere_mvp_contracts.md b/docs/arbsphere_mvp_contracts.md
new file mode 100644
index 0000000..76c258e
--- /dev/null
+++ b/docs/arbsphere_mvp_contracts.md
@@ -0,0 +1,76 @@
+ArbSphere MVP Contracts: Toy DSL Seeds and Canonical IR
+
+This document provides small, self-contained seeds for ArbSphere primitives that can be used by adapters to bootstrap interoperability in a two-venue MVP. The seeds follow the CatOpt-inspired canonical IR mapping used by EnergiBridge-like bridges.
+
+Primitives (DSL seeds)
+- LocalArbProblemSeed
+  - id: string
+  - venue: string
+  - asset_pair: string (e.g. "AAPL/MSFT")
+  - target_misprice: float
+  - max_exposure: float
+  - latency_budget_ms: int
+
+- SharedSignalsSeed
+  - version: int
+  - price_delta: float
+  - cross_venue_corr: float
+  - liquidity: float
+
+- PlanDeltaSeed
+  - actions: list of dicts with keys {venue_from, venue_to, instrument, size, time}
+  - timestamp: ISO8601 string
+  - delta_id: string
+  - signer: string (optional)
+  - signature: string (optional)
+
+- DualVariablesSeed
+  - multipliers: dict
+  - version: int
+
+- PrivacyBudgetSeed
+  - limit: float
+  - remaining: float
+  - expiration: ISO8601 string
+
+- AuditLogSeed
+  - entries: list of AuditLogEntrySeed
+
+- AuditLogEntrySeed
+  - ts: ISO8601 string or numeric
+  - event: string
+  - details: dict
+  - signature: string
+
+Example: two-venue MVP seed composition
+```
+LocalArbProblemSeed: {
+  id: "seed-venue-A-1",
+  venue: "venue-A",
+  asset_pair: "AAPL/MSFT",
+  target_misprice: 0.5,
+  max_exposure: 10000.0,
+  latency_budget_ms: 50
+}
+SharedSignalsSeed: {
+  version: 1,
+  price_delta: 0.12,
+  cross_venue_corr: 0.75,
+  liquidity: 20000.0
+}
+PlanDeltaSeed: {
+  actions: [ {venue_from: "venue-A", venue_to: "CROSS-VENUE", instrument: "AAPL/MSFT", size: 100, time: "2026-01-01T00:00:00Z"} ],
+  timestamp: "2026-01-01T00:00:00Z",
+  delta_id: "delta-001",
+  signer: "arb-issuer",
+  signature: "sig"
+}
+```
+
+Usage guidance
+- Adapters should map their vendor-specific data to these seeds before translation into the canonical IR.
+- The seeds are intended to be minimal, deterministic, and extensible as more primitives are added.
+
+Sanity checks
+- Validate that LocalArbProblemSeed.asset_pair is two-tuple string when exported to IR.
+- Ensure that PlanDeltaSeed.actions are deduplicated in downstream merges to support deterministic replay.