feat(PrivacyEngineering): add DifferentialPrivacyBudgetAllocation benchmark

benchmarks/PrivacyEngineering/DifferentialPrivacyBudgetAllocation/README.md

@@ -0,0 +1,58 @@
+# Differential Privacy Budget Allocation for Business Analytics
+
+Allocate a fixed differential-privacy budget across a batch of analytics queries. Each query has a sensitivity, business value, population coverage, minimum and maximum allowable epsilon, an error limit, and a population group. A solution must return one epsilon allocation per query.
+
+The verifier checks hard constraints first: exact query coverage, finite numeric allocations, per-query bounds, total budget, maximum estimation error, and bounded group-level average error disparity. Feasible solutions are scored by a positive raw utility metric owned by the verifier.
+
+## Candidate Interface
+
+Implement `solve(instance)` in `scripts/init.py`.
+
+Input fields:
+
+- `queries`: list of query objects.
+- `epsilon_total`: total privacy budget.
+- `fairness.max_group_error_ratio`: maximum allowed ratio between the largest and smallest group average error.
+
+Return:
+
+```python
+{"allocations": {query_id: epsilon, ...}}
+```
+
+The output must include exactly the query identifiers in the instance.
+
+## Scoring
+
+For feasible solutions, the raw metric is strictly positive and larger is better. It combines weighted analytics value with deterministic estimation-error penalties. Invalid or infeasible outputs receive the framework invalid score.
+
+Framework scoring uses `log2_baseline_ratio` normalization outside the verifier.
+
+<!-- BENCHGEN-PUBLIC-CONTRACT-START -->
+## Evaluation Contract
+
+The verifier recomputes `Verifier-owned positive raw utility: 1.0 plus the sum over queries of business_value * population_coverage * log1p(epsilon) minus deterministic error penalties, evaluated only after all feasibility checks pass.` and candidates must maximize it.
+Each valid case is scored by `log2` improvement over the baseline and the final score is the
+mean across cases. Invalid solutions receive `-1e18`.
+
+## Evaluation Design
+
+Setting: `offline_batch`. Arrival model: All analytics-query portfolios are generated deterministically from fixed seeds before solving. A candidate receives a complete static instance containing query sensitivities, business values, population coverage, group memberships, bounds, fairness thresholds, accuracy requirements, and total budget, then returns one structured allocation for that instance.
+
+Objective rationale: The primary objective is appropriate because privacy budget is a scarce resource and the economically relevant decision is the feasible allocation that preserves the most weighted analytics utility while controlling estimation error. Accuracy and fairness are hard feasibility requirements so the objective cannot trade them away beyond accepted policy limits.
+
+Literature alignment: The supplied brief aligns with differential-privacy budget-allocation work at the level of allocating limited privacy loss across multiple analytics queries and recomputing privacy loss and error from first principles. This benchmark differs by making the task an offline batch portfolio optimization problem with explicit business values, population coverage, fairness constraints, and a structured candidate output rather than an interactive privacy accountant or a single-query mechanism design task.
+
+Local execution is only for reviewed code:
+
+```bash
+python verification/evaluator.py scripts/init.py --local
+```
+
+Publish evaluation requires Docker and the pinned runtime image:
+
+```bash
+docker pull python:3.12.11-slim-bookworm@sha256:519591d6871b7bc437060736b9f7456b8731f1499a57e22e6c285135ae657bf7
+python verification/evaluator.py scripts/init.py
+```
+<!-- BENCHGEN-PUBLIC-CONTRACT-END -->

benchmarks/PrivacyEngineering/DifferentialPrivacyBudgetAllocation/README_zh-CN.md

@@ -0,0 +1,58 @@
+# 面向业务分析的差分隐私预算分配
+
+本任务要求在一批分析查询之间分配固定的差分隐私预算。每个查询都有敏感度、业务价值、覆盖人群比例、epsilon 上下界、最大误差限制以及所属人群组。解需要为每个查询返回一个 epsilon 分配值。
+
+验证器会先检查硬约束：查询 ID 是否完整且精确匹配、分配值是否为有限数字、是否满足每个查询的上下界、总预算、最大估计误差，以及组级平均误差差异限制。只有可行解才会计算由验证器定义的正向原始效用指标。
+
+## 参赛接口
+
+在 `scripts/init.py` 中实现 `solve(instance)`。
+
+输入字段：
+
+- `queries`：查询对象列表。
+- `epsilon_total`：总隐私预算。
+- `fairness.max_group_error_ratio`：最大允许的组间平均误差比值。
+
+返回：
+
+```python
+{"allocations": {query_id: epsilon, ...}}
+```
+
+输出必须精确包含实例中的所有查询 ID。
+
+## 评分
+
+对可行解，原始指标严格为正，且越大越好。该指标结合了加权业务价值和确定性的估计误差惩罚。无效或不可行输出由框架赋予无效分数。
+
+框架会在验证器外部使用 `log2_baseline_ratio` 进行归一化。
+
+<!-- BENCHGEN-PUBLIC-CONTRACT-START -->
+## 评测契约
+
+验证器会独立重算 `Verifier-owned positive raw utility: 1.0 plus the sum over queries of business_value * population_coverage * log1p(epsilon) minus deterministic error penalties, evaluated only after all feasibility checks pass.`，候选方案需要将其最大化。
+每个有效实例按照相对基线的 `log2` 改进计分，最终取所有实例分数的平均；
+无效方案得分为 `-1e18`。
+
+## 评测设计
+
+问题设定：`离线批量`。到达模型：All analytics-query portfolios are generated deterministically from fixed seeds before solving. A candidate receives a complete static instance containing query sensitivities, business values, population coverage, group memberships, bounds, fairness thresholds, accuracy requirements, and total budget, then returns one structured allocation for that instance.
+
+目标理由：The primary objective is appropriate because privacy budget is a scarce resource and the economically relevant decision is the feasible allocation that preserves the most weighted analytics utility while controlling estimation error. Accuracy and fairness are hard feasibility requirements so the objective cannot trade them away beyond accepted policy limits.
+
+文献对齐：The supplied brief aligns with differential-privacy budget-allocation work at the level of allocating limited privacy loss across multiple analytics queries and recomputing privacy loss and error from first principles. This benchmark differs by making the task an offline batch portfolio optimization problem with explicit business values, population coverage, fairness constraints, and a structured candidate output rather than an interactive privacy accountant or a single-query mechanism design task.
+
+本地执行只适用于已经审核的代码：
+
+```bash
+python verification/evaluator.py scripts/init.py --local
+```
+
+正式发布评测需要 Docker 和固定摘要的运行镜像：
+
+```bash
+docker pull python:3.12.11-slim-bookworm@sha256:519591d6871b7bc437060736b9f7456b8731f1499a57e22e6c285135ae657bf7
+python verification/evaluator.py scripts/init.py
+```
+<!-- BENCHGEN-PUBLIC-CONTRACT-END -->

benchmarks/PrivacyEngineering/DifferentialPrivacyBudgetAllocation/Task.md

@@ -0,0 +1,146 @@
+# Task
+
+You are given a batch of analytics queries and a fixed total differential-privacy budget. Allocate a nonnegative epsilon value to every query.
+
+Each query contains:
+
+- `id`: query identifier.
+- `sensitivity`: sensitivity used in the deterministic error model.
+- `business_value`: value weight for the query.
+- `population_coverage`: covered population fraction or weight.
+- `epsilon_min`: minimum allowed privacy budget.
+- `epsilon_max`: maximum allowed privacy budget.
+- `max_error`: maximum allowed estimation error.
+- `group`: population group label used for fairness checks.
+
+The estimation error for a query is `sensitivity / epsilon`. Allocations must satisfy every per-query bound, every per-query maximum error, the total budget limit, and the group fairness ratio over average group errors.
+
+## Required Output
+
+Return a dictionary with one key:
+
+```python
+{
+  "allocations": {
+    "query_id": epsilon
+  }
+}
+```
+
+The allocation map must contain exactly the required query IDs and finite numeric epsilon values.
+
+## Objective
+
+After feasibility checks pass, the verifier computes a positive raw utility. Larger values are better. The metric rewards useful analytics budget and penalizes estimation error. Normalization is handled by the benchmark framework.
+
+<!-- BENCHGEN-PUBLIC-CONTRACT-START -->
+## Input Schema
+
+```json
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "queries",
+    "epsilon_total",
+    "fairness"
+  ],
+  "properties": {
+    "queries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "sensitivity",
+          "business_value",
+          "population_coverage",
+          "epsilon_min",
+          "epsilon_max",
+          "max_error",
+          "group"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "sensitivity": {
+            "type": "number",
+            "minimum": 0
+          },
+          "business_value": {
+            "type": "number",
+            "minimum": 0
+          },
+          "population_coverage": {
+            "type": "number",
+            "minimum": 0
+          },
+          "epsilon_min": {
+            "type": "number",
+            "minimum": 0
+          },
+          "epsilon_max": {
+            "type": "number",
+            "minimum": 0
+          },
+          "max_error": {
+            "type": "number",
+            "minimum": 0
+          },
+          "group": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "epsilon_total": {
+      "type": "number",
+      "minimum": 0
+    },
+    "fairness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "max_group_error_ratio"
+      ],
+      "properties": {
+        "max_group_error_ratio": {
+          "type": "number",
+          "minimum": 1
+        }
+      }
+    }
+  }
+}
+```
+
+## Output Schema
+
+```json
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "allocations"
+  ],
+  "properties": {
+    "allocations": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}
+```
+
+## Constraints and Objective
+
+The output must satisfy every hard constraint described above. The frozen verifier independently
+checks feasibility and recomputes `Verifier-owned positive raw utility: 1.0 plus the sum over queries of business_value * population_coverage * log1p(epsilon) minus deterministic error penalties, evaluated only after all feasibility checks pass.`. The objective is to maximize
+that strictly positive raw metric. Valid cases use `log2` baseline improvement and are aggregated
+with the mean; invalid solutions receive `-1e18`.
+
+The problem setting is `offline_batch`. Objective rationale: The primary objective is appropriate because privacy budget is a scarce resource and the economically relevant decision is the feasible allocation that preserves the most weighted analytics utility while controlling estimation error. Accuracy and fairness are hard feasibility requirements so the objective cannot trade them away beyond accepted policy limits.
+Literature alignment: The supplied brief aligns with differential-privacy budget-allocation work at the level of allocating limited privacy loss across multiple analytics queries and recomputing privacy loss and error from first principles. This benchmark differs by making the task an offline batch portfolio optimization problem with explicit business values, population coverage, fairness constraints, and a structured candidate output rather than an interactive privacy accountant or a single-query mechanism design task.
+<!-- BENCHGEN-PUBLIC-CONTRACT-END -->