moon-privacy-budget

A comprehensive, auditable Differential Privacy Budget Manager for MoonBit.

differential-privacy

privacy-budget

laplace

gaussian

rdp

privacy-ledger

Download zip

Author

ppyq882

Version

0.1.1

License

Apache-2.0

Repository

github.com/ppyq882/moon-privacy-budget

Last updated

2 months ago

Downloads

No dependencies

#moon-privacy-budget

面向 MoonBit 的可审计差分隐私预算管理器。项目把预算策略、账户账本、预留/提交事务、私密查询计划、批量执行和审计导出组合成一条可验证的工作流，适合数据分析服务、隐私 SQL 网关和需要预算追踪的实验性 ML 流水线。

#项目定位

moon-privacy-budget 解决的是“查询可以加噪，但预算不能失控”的工程问题：每次查询先经过输入与策略校验，再调用差分隐私机制；成功查询才扣减预算，拒绝和失败路径保留审计信息且不产生虚假消耗。

项目提供的是库优先的 MoonBit API，同时附带一个可复现的 CLI 演示和基准入口。算法机制与预算管理分层，调用方可以替换查询入口、账本存储或审计导出，而不需要改动核心聚合器。

#核心能力

预算类型、ε/δ 校验、查询行数/查询次数/单次预算/最低剩余预算策略。
PrivacyAccount 账户扣减、告警状态、账户查询计数，以及 PrivacyLedger 的预留、提交、回滚、使用快照和确定性账本 reconciliation 报告。
Interactive、Batch、Strict Audit 三类经过验证的预算策略预设，支持统一元数据、策略检查和运行模式复用。
Laplace、Gaussian、Analytic Gaussian、Exponential、SVT、Randomized Response、Matrix Mechanism 等差分隐私机制。
QueryPlan 对表名、列、过滤条件、分组和 LIMIT 做结构化校验；SQL 解析器拒绝缺失子句、非法数值和尾随 token。
PrivacyGuard::execute_plan 在机制执行前实施策略检查；execute_query_batch 支持共享预算下的有序批处理、逐项结果和失败隔离。
审计生命周期汇总、账户/数据集/机制分组、拒绝原因计数和异常分析，支持 JSON 和 Markdown 导出，包含请求预算、实际消耗、状态和时间戳。
wasm-gc、wasm、JS 检查；Unix CI 额外执行 native 测试。

#快速开始

环境要求：安装 MoonBit 官方 stable 工具链。仓库 CI 使用官方安装脚本获取最新 stable；本地可用 moon version --all 查看版本。

git clone https://github.com/ppyq882/moon-privacy-budget.git
cd moon-privacy-budget

moon update
moon check --target all --deny-warn
moon test --deny-warn
moon run main -- demo

库代码可以直接作为 MoonBit module 依赖使用：

let budget = match @core.PrivacyBudget::make(1.0, 0.0001) {
  Ok(value) => value
  Err(error) => fail(error)
}
let account = @ledger.PrivacyAccount::new("analyst", "service", budget, 100)
let policy = match @core.BudgetPolicy::new(
  budget,
  @core.PrivacyBudget::zero(),
  100,
  100000,
) {
  Ok(value) => value
  Err(error) => fail(error)
}
let guard = @query.PrivacyGuard::with_policy(account, policy, 42UL)
let plan = @query.QueryPlan::new(
  @query.QueryType::select_count(),
  "events",
)
let result = guard.execute_plan("query-001", table, plan, budget)

#CLI

CLI 是库 API 的最小可运行入口：

moon run main -- help
moon run main -- demo
moon run main -- benchmark
moon run main -- version

benchmark 构造 10,000 行确定性表，解析带过滤和 LIMIT 的 SELECT COUNT(*) 计划，执行 50 次 DP 查询，并输出完成数、计时器 ticks 和最后一次噪声结果。

#架构

main/                 CLI、演示和基准入口
src/core/             ε/δ、预算、敏感度、策略
src/math/             PRNG、分布、矩阵与数值工具
src/mechanisms/       基础差分隐私机制
src/aggregators/      COUNT、SUM、MEAN、VARIANCE、HISTOGRAM
src/ledger/            账户、账本、预留、过滤器、里程表
src/query/            表、SQL、计划、守卫、批执行
src/audit/            日志、生命周期汇总、分组分析、JSON/Markdown 导出
src/composition/      Basic、Advanced、RDP、zCDP、Moments Accountant
src/federated/        联邦节点与预算协调
src/ml/               DP-SGD 与隐私机器学习示例

数据流为：

SQL / QueryPlan -> schema validation -> BudgetPolicy -> DP mechanism
                                      -> account charge -> audit export

查询计划还提供 canonical_sql() 和 explain(table)，可用于日志关联、调试和执行前的行数估算。

#基准

以下是本地 Windows 工作区使用仓库 CLI 的实际输出样本；连续 5 次运行的 elapsed_ticks 为 7、6、10、7、7，中位数为 7。该计时器依赖运行环境，只用于同一环境的回归比较，不代表跨机器性能承诺。

benchmark=private_count
rows=10000
iterations=50
completed=50
elapsed_ticks=7
last_noisy_count=4990.782381400174

运行方式：

moon run main -- benchmark

#测试与质量门禁

moon fmt --check
moon info
moon check --target all --deny-warn
moon test --deny-warn
moon test --target wasm-gc --deny-warn
moon test --target js --deny-warn

当前仓库包含 90 个有效 .mbt 文件、9,204 个非空 MoonBit 源码行：其中生产代码 6,787 行、测试 2,417 行；统计基于 Git 跟踪的 .mbt 文件，排除了 _build 和 pkg.generated.mbti。测试覆盖预算边界、负数/NaN/越界数据、非法计划、空过滤结果、重复批处理 ID、预留生命周期、账本一致性、策略预设、审计分组/异常/导出和跨模块端到端路径。