build(agent): new-agents#a6e6ec iteration

.gitignore

@@ -0,0 +1,21 @@
+node_modules/
+.npmrc
+.env
+.env.*
+__tests__/
+coverage/
+.nyc_output/
+dist/
+build/
+.cache/
+*.log
+.DS_Store
+tmp/
+.tmp/
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+READY_TO_PUBLISH

AGENTS.md

@@ -0,0 +1,40 @@
+# ExProve SWARM Guidelines
+
+Architecture overview
+- Canonical primitives form the Covariant IR for cross-venue execution provenance:
+  - LocalExecutionTask: per-instrument, per-venue planning unit
+  - SharedMarketContext: privacy-safe, versioned market signals
+  - PlanDelta: incremental routing/size/timing decisions with metadata
+  - Attestation/AuditLog: cryptographic attestations and append-only logs
+  - Graph-of-Contracts: adapters and data-contract schemas
+- Edge-native solver: lightweight optimizer co-located with venue data to produce PlanDelta
+- Delta-sync with deterministic replay for offline backtesting and regulatory review
+- Governance ledger: cryptographic signing, policy hooks, optional cloud anchoring
+- Adapters marketplace: plug-in venue adapters translating venue data into canonical IR
+
+MVP plan (8–12 weeks)
+- Phase 0: Skeleton protocol, 2 starter adapters, toy objective (VWAP-like), deterministic delta-sync
+- Phase 1: Governance scaffolding, identity management, secure aggregation for SharedMarketContext
+- Phase 2: Cross-venue demo in simulated env; publish ExProve SDK and minimal contract example
+- Phase 3: Backtesting harness and deterministic replay; compliance-report generator
+
+Deliverables
+- Core data contracts: LocalExecutionTask, SharedMarketContext, PlanDelta, Attestation, AuditLog, Graph-of-Contracts
+- Toy adapters (2 starters) and conformance harness
+- Seed DSL for LocalExecutionTask/SharedMarketContext/PlanDelta
+- Reference ExProve SDK (Python/C++ bindings) and transport layer
+
+Testing and QA
+- Lightweight conformance harness and toy adapters (end-to-end replay tests)
+- Deterministic tests for PlanDelta generation
+- Audit-ready logs and crypto tagging (signatures stubs for MVP)
+
+Repository rules
+- Use Python for core MVP; keep dependencies minimal
+- Add test.sh that builds and runs tests; ensure python packaging compiles
+- If you add external dependencies, update pyproject.toml and keep tests deterministic
+
+Contributing
+- Follow the existing coding style in this repo; keep changes minimal and well-scoped
+- Add tests for any bug fixes or new primitives
+- Update README with usage notes and contributor guidelines

README.md

@@ -1,3 +1,19 @@
-# idea160-exprove-open-source
+# ExProve: Open-Source Execution Provenance Engine for Cross-Venue Equity Trading
 
-Source logic for Idea #160
+ExProve provides a minimal, production-oriented MVP for verifiable cross-venue execution provenance.
+
+- Core primitives: LocalExecutionTask, SharedMarketContext, PlanDelta, Attestation, AuditLog, GraphOfContracts
+- Edge-native planner: deterministic PlanDelta generation for replay and backtesting
+- Deterministic delta-synchronization for offline replay
+- Python-based MVP with a small test suite and packaging metadata
+
+- How to run
+  1. Install dependencies via pyproject.toml (build uses setuptools)
+  2. Run test script: bash test.sh
+- What’s included
+  - AGENTS.md: SWARM guidelines and MVP plan
+  - src/exprove: core primitives and engine
+  - tests/test_exprove_basic.py: basic unit tests
+  - test.sh: build and test harness
+
+This README should evolve as the MVP matures and more adapters and backtests are added.

pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "exprove-core"
+version = "0.0.1"
+description = "Open, verifiable execution provenance primitives for cross-venue equity trading"
+requires-python = ">=3.8"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["exprove*"]

src/exprove/__init__.py

@@ -0,0 +1,20 @@
+"""ExProve core primitives package.
+
+This minimal MVP provides:
+- LocalExecutionTask
+- SharedMarketContext
+- PlanDelta
+- Attestation
+- AuditLog
+- GraphOfContracts
+"""
+from .contracts import LocalExecutionTask, SharedMarketContext, PlanDelta, Attestation, AuditLog, GraphOfContracts
+
+__all__ = [
+    "LocalExecutionTask",
+    "SharedMarketContext",
+    "PlanDelta",
+    "Attestation",
+    "AuditLog",
+    "GraphOfContracts",
+]

src/exprove/contracts.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, asdict, field
+from typing import Any, Dict, List, Optional
+
+
+def to_json(obj: Any) -> str:
+    return json.dumps(obj, default=lambda o: o.__dict__, sort_keys=True)
+
+
+@dataclass
+class LocalExecutionTask:
+    task_id: str
+    instrument: str
+    venue: str
+    objective: str
+    constraints: Dict[str, Any] = field(default_factory=dict)
+
+    def to_json(self) -> str:
+        return to_json(asdict(self))
+
+
+@dataclass
+class SharedMarketContext:
+    signals: Dict[str, Any]
+    version: int
+    contract_id: str
+
+    def to_json(self) -> str:
+        return to_json(asdict(self))
+
+
+@dataclass
+class PlanDelta:
+    delta: Dict[str, Any]
+    timestamp: float
+    author: str
+    contract_id: str
+    privacy_budget: Optional[float] = None
+
+    def to_json(self) -> str:
+        return to_json(asdict(self))
+
+
+@dataclass
+class Attestation:
+    entry: str
+    signer: str
+    timestamp: float
+    contract_id: str
+    version: int
+
+    def to_json(self) -> str:
+        return to_json(asdict(self))
+
+
+@dataclass
+class AuditLog:
+    entries: List[Attestation] = field(default_factory=list)
+
+    def add(self, at: Attestation) -> None:
+        self.entries.append(at)
+
+    def to_json(self) -> str:
+        return to_json([asdict(e) for e in self.entries])
+
+
+@dataclass
+class GraphOfContracts:
+    adapters: Dict[str, Any]
+    version: int
+    registry_id: str
+
+    def to_json(self) -> str:
+        return to_json(asdict(self))

src/exprove/engine.py

@@ -0,0 +1,58 @@
+"""A tiny, deterministic edge-native planner placeholder.
+
+Given a LocalExecutionTask and SharedMarketContext, produce a PlanDelta
+ deterministically using a stable hash seed. This is intentionally minimal
+ but deterministic to support replay in backtesting.
+"""
+
+import hashlib
+import time
+from typing import Any, Dict
+
+from .contracts import LocalExecutionTask, SharedMarketContext, PlanDelta
+
+
+def _deterministic_delta(task: LocalExecutionTask, ctx: SharedMarketContext) -> Dict[str, Any]:
+    seed_input = f"{task.task_id}:{task.instrument}:{task.venue}:{ctx.version}:{ctx.contract_id}"
+    h = hashlib.sha256(seed_input.encode("utf-8")).hexdigest()
+    # Deterministic small delta: a suggested route and a size adjustment heuristic
+    delta = {
+        "route": [task.venue],  # naive: route to the requested venue
+        "size_adjustment": int(h[:6], 16) % 1000,  # some deterministic sizing tweak
+        # Deterministic replay: timestamp set to a fixed value for determinism
+        "timestamp": 0.0,
+        "hash_seed": h,
+    }
+    return delta
+
+
+def compute_plan_delta(task: LocalExecutionTask, ctx: SharedMarketContext, *, author: str) -> PlanDelta:
+    delta = _deterministic_delta(task, ctx)
+    return PlanDelta(
+        delta=delta,
+        timestamp=0.0,
+        author=author,
+        contract_id=ctx.contract_id,
+        privacy_budget=None,
+    )
+
+
+def main():
+    # Simple CLI-friendly demonstration (not imported by tests)
+    import json
+
+    # Example wiring; in real usage this would be from inputs
+    task = LocalExecutionTask(
+        task_id="demo-001",
+        instrument="AAPL",
+        venue="VenueA",
+        objective="VWAP-tracking",
+        constraints={"latency_ms": 50},
+    )
+    ctx = SharedMarketContext(signals={"depth": 5}, version=1, contract_id="contract-1")
+    delta = compute_plan_delta(task, ctx, author="engine")
+    print(delta.to_json())
+
+
+if __name__ == "__main__":
+    main()

test.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+set -euo pipefail
+
+# Build and test ExProve MVP
+echo "==> Building package..."
+python3 -m build
+
+echo "==> Running tests..."
+pytest -q
+
+echo "==> All tests passed."

tests/test_exprove_basic.py

@@ -0,0 +1,51 @@
+import json
+import sys
+import os
+
+# Ensure the src/ directory is on PYTHONPATH for tests when running from repo root
+repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+src_dir = os.path.join(repo_root, "src")
+if src_dir not in sys.path:
+    sys.path.insert(0, src_dir)
+
+from exprove import LocalExecutionTask, SharedMarketContext, PlanDelta
+from exprove.engine import compute_plan_delta
+
+
+def test_local_execution_task_serialization():
+    t = LocalExecutionTask(
+        task_id="t1",
+        instrument="GOOG",
+        venue="VenueX",
+        objective="VWAP",
+        constraints={"latency": 10},
+    )
+    s = t.to_json()
+    assert isinstance(s, str)
+    d = json.loads(s)
+    assert d["task_id"] == "t1"
+    assert d["instrument"] == "GOOG"
+
+
+def test_engine_deterministic_delta():
+    task = LocalExecutionTask(
+        task_id="t2",
+        instrument="MSFT",
+        venue="VenueY",
+        objective="VWAP",
+        constraints={"latency": 5},
+    )
+    ctx = SharedMarketContext(signals={"depth": 10}, version=2, contract_id="c-2")
+    delta1 = compute_plan_delta(task, ctx, author="engine")
+    delta2 = compute_plan_delta(task, ctx, author="engine")
+    assert delta1.delta == delta2.delta
+    assert delta1.timestamp <= delta2.timestamp  # non-decreasing timestamp on re-run is fine
+
+
+def test_attestation_and_auditlog_serialization():
+    from exprove.contracts import Attestation, AuditLog
+    a = Attestation(entry="delta committed", signer="issuer", timestamp=1.0, contract_id="c-3", version=1)
+    log = AuditLog()
+    log.add(a)
+    j = log.to_json()
+    assert isinstance(j, str)