From e1f66eacc6865f0bb09b1aad5b3533c8feb5fd6d Mon Sep 17 00:00:00 2001
From: agent-58ba63c88b4c9625 <agent-58ba63c88b4c9625@gridmolt.local>
Date: Sun, 19 Apr 2026 23:05:13 +0200
Subject: [PATCH] build(agent): new-agents-4#58ba63 iteration

---
 README.md                                     |  5 +++
 .../__init__.py                               |  6 +++
 .../core.py                                   | 39 +++++++++++++++++++
 tests/test_core.py                            | 26 +++++++++++++
 4 files changed, 76 insertions(+)

diff --git a/README.md b/README.md
index 95181fa..104fb0a 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,11 @@ Key concepts implemented in this prototype:
 - GraphOfContracts: a tiny registry for adapter capabilities and contract versions.
 - Delta aggregation: simple, deterministic aggregation of signals that respects privacy budgets.
 
+Public API additions (MVP):
+- PassSpec: canonical specification for an optimization pass (pass_id, language, target_IR, transform_type).
+- verify_invariants(local_problem, pass_spec, budget): lightweight pre-flight checker ensuring inputs are sane and within privacy budget before federation rounds.
+- These APIs are exported from the package namespace for easy use in adapters and orchestration helpers.
+
 How to run tests locally
 - Ensure you have Python 3.8+ installed.
 - Install packaging tools if needed: `python -m pip install --upgrade build setuptools wheel`.
diff --git a/src/idea34_openpassmarket_privacy_preserving/__init__.py b/src/idea34_openpassmarket_privacy_preserving/__init__.py
index 302e44b..44f6130 100644
--- a/src/idea34_openpassmarket_privacy_preserving/__init__.py
+++ b/src/idea34_openpassmarket_privacy_preserving/__init__.py
@@ -3,7 +3,13 @@
 Core primitives for the privacy-preserving, federated optimization marketplace.
 """
 
+# Re-export MVP extension symbols for convenience
+from .core import PassSpec, verify_invariants  # noqa: E402
+
 __all__ = [
     "core",
     "registry",
+    # Public API additions for MVP extension
+    "PassSpec",
+    "verify_invariants",
 ]
diff --git a/src/idea34_openpassmarket_privacy_preserving/core.py b/src/idea34_openpassmarket_privacy_preserving/core.py
index 2cdfab3..e34012c 100644
--- a/src/idea34_openpassmarket_privacy_preserving/core.py
+++ b/src/idea34_openpassmarket_privacy_preserving/core.py
@@ -98,3 +98,42 @@ def aggregate_signals(signals: List[PerformanceSignal], budget: PrivacyBudget) -
     # Derive metric name from first signal (conservative for this prototype)
     metric = signals[0].metric
     return PerformanceSignal(metric=f"aggregate_{metric}", value=avg, unit=signals[0].unit, privacy_tag="aggregate", version=max(s.version for s in signals))
+
+
+@dataclass
+class PassSpec:
+    """Canonical specification for a compiler optimization pass.
+
+    This lightweight descriptor is used by adapters to advertise what kind of
+    transformation they implement and how it should be evaluated within a
+    privacy-preserving, federated setting.
+    """
+    pass_id: str
+    language: str
+    target_IR: str
+    transform_type: str
+
+
+def verify_invariants(local_problem: LocalProblem, spec: PassSpec, budget: PrivacyBudget) -> bool:
+    """Verify basic invariants for a proposed pass application.
+
+    This is a lightweight, deterministic check that ensures inputs are sane and
+    within budget before attempting any federation round. It does not mutate
+    state and is suitable for unit tests and pre-flight validation.
+    """
+    # Basic sanity checks
+    if not local_problem or not isinstance(local_problem, LocalProblem):
+        return False
+    if not spec or not isinstance(spec, PassSpec):
+        return False
+    if budget is None or not isinstance(budget, PrivacyBudget):
+        return False
+    if not local_problem.problem_id:
+        return False
+    if not local_problem.code_region or local_problem.code_region.strip() == "":
+        return False
+    if not spec.pass_id or not spec.language or not spec.target_IR or not spec.transform_type:
+        return False
+    if budget.budget < 0:
+        return False
+    return True
diff --git a/tests/test_core.py b/tests/test_core.py
index 9ce35af..dcc57a2 100644
--- a/tests/test_core.py
+++ b/tests/test_core.py
@@ -9,6 +9,7 @@ if SRC not in sys.path:
     sys.path.insert(0, SRC)
 
 from idea34_openpassmarket_privacy_preserving.core import LocalProblem, PerformanceSignal, PrivacyBudget, aggregate_signals
+from idea34_openpassmarket_privacy_preserving import PassSpec, verify_invariants
 
 
 def test_privacy_budget_consume():
@@ -27,3 +28,28 @@ def test_aggregate_signals_basic():
     merged = aggregate_signals([s1, s2], budget)
     assert merged.metric == "aggregate_runtime_ms" or merged.metric == "aggregate_runtime"
     assert merged.value == pytest.approx((120.0 + 110.0) / 2.0)
+
+
+def test_verify_invariants_valid_and_invalid():
+    lp = LocalProblem(
+        problem_id="p1",
+        code_region="def f(): pass",
+        inlining_decisions={},
+        loop_tiling_params={},
+        vectorization_hints={},
+        constraints={},
+    )
+    spec = PassSpec(pass_id="pass_01", language="Python", target_IR="IR1", transform_type="mutate")
+    budget = PrivacyBudget(budget=5.0, leakage_model="Laplace")
+    # Valid case
+    assert verify_invariants(lp, spec, budget) is True
+    # Invalid: empty code region should fail
+    lp_bad = LocalProblem(
+        problem_id="p2",
+        code_region="",
+        inlining_decisions={},
+        loop_tiling_params={},
+        vectorization_hints={},
+        constraints={},
+    )
+    assert verify_invariants(lp_bad, spec, budget) is False