diff --git a/AGENTS.md b/AGENTS.md index 2d02ddd..a815f81 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,3 +29,14 @@ Tests & packaging: How to contribute: - Implement real adapters, enhance solver, and hook up a real consensus/secure-aggregation layer - Add integration tests for end-to-end edge-to-edge flow + +Enhancements plan (ELAC-Plan MVP refinement) +- Canonical primitives and interoperability: map ELAC primitives to a CatOpt-inspired canonical IR + - LocalProblem -> Object, SharedVariables -> Morphisms, PlanDelta -> PlanDelta, DualVariables -> DualVariables, AuditLog -> Governance/Provenance +- MVP wiring (8–12 weeks, 2–3 adapters): phase 0 skeleton + 2 adapters (venue-feed and broker gateway) over TLS; lightweight local solver; deterministic end-to-end delta-sync; toy cross-venue objective +- Phase 1: governance ledger scaffolding and identity layer; adapter conformance tests +- Phase 2: cross-domain demo in a simulated environment; publish a reference ELAC SDK +- Phase 3: hardware-in-the-loop testing; latency, plan quality, delta-sync costs, and privacy budgets +- Security and privacy: TEEs/hardware attestation for edge solvers; secure aggregation; possible zk-proofs +- Testing and metrics: latency, convergence, data-sharing volume, and governance auditability coverage +- Artifacts: draft DSL sketch (LocalProblem/SharedVariables/PlanDelta/DualVariables/AuditLog), toy adapters, minimal transport spec, RFC for registry surface diff --git a/README.md b/README.md index 37c0f15..c5beb23 100644 --- a/README.md +++ b/README.md @@ -20,3 +20,8 @@ How to run (dev): - Run API locally (example): uvicorn elac_plan.api:app --reload This is a minimal but production-conscious MVP intended to be extended by adding governance ledger, secure aggregation, and real adapters in subsequent iterations. + +Interop and roadmap +- See docs/elac_plan_interop.md for a minimal DSL sketch and EnergiBridge-style interoperability planning (LocalProblem/SharedVariables/PlanDelta/DualVariables/AuditLog). +- The MVP already includes two adapters (NBBOFeedAdapter and BrokerGatewayAdapter) and a toy LocalSolver for end-to-end delta-sync. +- The plan includes phases for governance, secure aggregation, cross-venue demos, and HIL testing; reference SDK and sample DSL are provided for integration with other domains. diff --git a/docs/elac_plan_interop.md b/docs/elac_plan_interop.md new file mode 100644 index 0000000..51f7bda --- /dev/null +++ b/docs/elac_plan_interop.md @@ -0,0 +1,82 @@ +ELAC-Plan Interoperability and DSL Sketch + +Overview +- ELAC-Plan defines a canonical primitive set for cross-venue execution planning: +- Objects/LocalProblem: per-asset, per-venue optimization tasks +- Morphisms/SharedVariables: privacy-bounded market signals +- DualVariables: cross-venue coupling signals (shadow prices) +- PlanDelta: incremental plan updates with provenance metadata +- AuditLog: cryptographic provenance and governance events + +Interoperability mapping ( EnergiBridge-style ) +- Map ELAC primitives to a simple, vendor-agnostic IR: + - LocalProblem -> Object: id, asset, venue, objective, constraints, price_target, tolerance + - SharedVariables -> Morphisms: contract_id, version, variables + - PlanDelta -> PlanDelta: delta, timestamp, author, contract_id, privacy_budget + - DualVariables -> DualVariables: contract_id, version, shadow_prices + - AuditLog -> AuditLog: entries with event, timestamp, hash, details + +Minimal DSL sketch (Python dataclasses used in tests) +```python +from dataclasses import dataclass +from typing import Dict, Any + +@dataclass +class DSLObject: + id: str + asset: str + venue: str + objective: str + constraints: Dict[str, Any] + price_target: float + tolerance: float + +@dataclass +class DSLMorphisms: + contract_id: str + version: int + variables: Dict[str, Any] + +@dataclass +class DSLDualVariables: + contract_id: str + version: int + shadow_prices: Dict[str, float] + +@dataclass +class DSLPlanDelta: + contract_id: str + delta: Dict[str, Any] + timestamp: str + author: str + privacy_budget: float +``` + +Toy two-adapter MVP (Phase 0) +- 2 starter adapters: + - NBBOFeedAdapter: translates NBBO-like quotes into SharedVariables (privacy-bounded) + - BrokerGatewayAdapter: publishes PlanDelta to a broker API (TLS transport conceptually) +- Lightweight LocalSolver that consumes LocalProblem and emits PlanDelta +- End-to-end delta-sync with deterministic replay on reconnects +- Toy cross-venue objective (e.g., simple arb or spread capture) + +Phase plan (high level) +- Phase 0: Protocol skeleton + 2 adapters + TLS; deterministic delta-sync; local objective +- Phase 1: Governance ledger scaffolding; identity layer; adapter conformance checks +- Phase 2: Cross-venue demo in simulated environments; reference ELAC SDK +- Phase 3: Performance and privacy budget evaluation + +Security and governance principles +- TEEs/isolations for edge solvers; per-message crypto-tags +- Secure aggregation for SharedVariables; optional zk-proofs +- Tamper-evident governance ledger anchored to a lightweight ledger or hash chain +- DID-based identity certificates for adapters + +Testability and metrics +- Latency: data feed -> plan delta at edge +- Delta-sync turnaround and convergence speed +- Plan quality vs centralized baseline +- Privacy budget leakage budgets +- Adapter conformance and governance coverage + +If helpful, I can draft concrete DSL sketches for additional primitives or extend the toy MVP with a lightweight TLS transport layer and simulated venues. diff --git a/test.sh b/test.sh old mode 100644 new mode 100755