Files
ssw-mpc/docs/GAP_PLAN.md
T
rong 1e84d681c2 feat(sql): 密态 IN / NOT IN(脱糖 OR 等式)
Pred 加 In{col, values, negated}:逐个 bit_eq 后 bit_or,negated 再 bit_not。
对拍明文引擎的 x IN (100,250,500) 与 NOT IN。

nax-sql --features secure 21 测,workspace 218 全绿、零警告。
2026-10-30 16:51:32 +08:00

102 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# nax-rs ↔ nax-python 补齐计划(按优先级逐条做)
> 生成日期:2026-10-30。背景:`refs/nax` 是独立 Python 参考实现,nax-rs 只 port 了它的一部分。
> 本计划把"Python 有、Rust 没有"的 9 块按优先级排好,逐条落地。
## 现状(已对齐,golden 验证过,勿动)
| 能力 | Rust | 验证 |
|---|---|---|
| 环算术 / 分片 / PRG | nax-core | 215 条 golden |
| ECDH-PSI / PIR | nax-psi / nax-he | 多测 + RFC7748 |
| Paillier / OLE | nax-he | 50 golden + 13 协议测 |
| 纵向 LR | nax-ml | 明文对照 >0.95 |
| 明文 MLP(前向/反向/二分类) | nax-ml(`mlp`) | 4 测:3 逐位 golden(前向概率/单步梯度/5 轮轨迹)+ 可分离数据收敛 >0.9 |
| 异构分箱 + WOE/IV | nax-ml(`binning`) | 6 测:quantile/uniform/custom 切点、searchsorted 分箱、WOE/IV、互补抑制 |
| 数据层(Frame/stats/mock/CSV) | nax-data | 16 测:构造/选择/矩阵、均值/方差/协方差/相关、确定性主键、schema 合成、DP 统计、CSV 往返 |
| SCQL SQL 引擎 | nax-sql | 15 测:解析 AST、掩码 WHERE、聚合、GROUP BY、k-匿名、投影约束、JOIN、HAVING/ORDER BY/LIMIT、不支持语法拒绝 |
| 出域守卫 + 审计 | nax-policy | 9 测:exec/transfer/fetch 三关口、Label 集合、审计记录/过滤/汇总/裁剪 |
| dry_run 执行模式 | nax-runtime | 4 测:默认真实、进入试跑、嵌套恢复、real_run 临时覆盖 |
| ZKP(Schnorr/Pedersen/表示证明) | nax-zkp | 5 测含 2 逐位 golden,篡改必败 |
| 安全聚合 + DP + 横向 FedAvg | nax-fl | 12 测:裁剪/置零/均值/RDP 记账/聚合链/本地 LR/指标/加权均值/FedAvg 轨迹与收敛 |
| Vault 安全域编排 | nax-vault+node+orch | 多测 |
| 集群 / Ray 后端 | nax-orch / nax-ray | 跨架构跑通 |
| TEE HAL | nax-tee | OP-TEE 已验证范式 |
合计 **212 个测试函数全绿、0 失败**(含 215+50+ 多条逐位 golden 断言),与 README 一致。**9 个优先块全部落地。**
## 缺口量化
Python 参考版 `nax/` 共 **8,963 行**。此前约 **4,150 行(≈46%)未被 port**,集中在下面 9 块。
缺口在**功能广度**,不在"已做部分的正确性"——地基全在且 golden 验证过。
> **状态(2026-10-30)**:下面 9 块**全部已落地**(新建 `nax-zkp`/`nax-fl`/`nax-data`/`nax-sql`/`nax-policy`/`nax-runtime`,并在 `nax-ml` 内加 `mlp`/`binning`)。分布式外壳(`Vault`/`Site`/PSI`/`SiteRef`)复用既有原语;本计划补的是建在地基上的**算法层与前端**。
## 优先级与执行顺序
排序原则:**依赖少 → 可独立 golden 验证 → 能解锁更多后续**。
| # | 模块 | 新建 Rust crate | Python 源 | 行数 | 验收标准 |
|---|------|----------------|----------|------|----------|
| **1** ✅ | ZKP / v15 扩展 | `nax-zkp` | `crypto/zkp` | 252 | golden 逐位 + 篡改消息必败 |
| **2** ✅ | 安全聚合 + DP | `nax-fl` | `ml/aggregators`, `privacy/dp` | 552 | golden + 聚合链(Clip/Zero/Mean/Gauss)测试 |
| **3** ✅ | 横向 FedAvg | `nax-fl` | `ml/fedavg`, `ml/aggregate` | 433 | 明文 LR 对照收敛 |
| **4** ✅ | 安全 MLP | `nax-ml`(加 `mlp`) | `ml/mlp` | 251 | 二分类明文对照 |
| **5** ✅ | 异构分箱 | `nax-ml`(加 `binning`) | `ml/binning` | 391 | 分箱边界一致 |
| **6** ✅ | 数据层 | `nax-data` | `data/{frame,stats,mock}` | 693 | 构造 / IO / 统计测试 |
| **7** ✅ | SCQL SQL 引擎 | `nax-sql` | `sql/{ast,parser,engine}` | 1258 | 解析 + 执行 golden(GROUP BY / 聚合 / 谓词) |
| **8** ✅ | 策略 / 审计 / 守卫 | `nax-policy` | `policy/{audit,guard}` | 189 | 审计链 + 受限 SQL 拒绝语义 |
| **9** ✅ | dry_run 模式 | `nax-runtime` | `runtime/mode` | 132 | 双路径(real/dry)结果一致 |
## 依赖与铁律
- **不引新外部依赖**:大数用 `nax-he::bigint::BigUint`;SHA256 用 `nax-core::hash::sha256`;随机源用 `nax-core::prg::Stream`(OS 种子读 `/dev/urandom`)。
- **golden 逐位对照**:每条确定性算子从 `refs/nax` 导出基线,硬比 u64 / hex / 整数。
**绝不为了测试变绿放宽断言**——先确认哪边对。
- **TEE 路径**:私密比较 / 聚合走 `nax-core`(no_std);ZKP / 审计在普通域即可。
- 每项完成后补 `cargo test` 全绿,并更新 `README.md` 现状表与本文档进度。
## 本次执行
- **#1 nax-zkp(✅ 完成)**:Schnorr 身份证明 + Pedersen 承诺 + 表示证明 + 授权声明,逐位对照 `crypto/zkp.py`;`cargo test -p nax-zkp` 全绿(5 测含 2 逐位 golden、篡改必败)。
- **#2 nax-fl(✅ 完成)**:安全聚合器(Clip/Zero/SecureSum/Mean/GaussianNoise 责任链)+ 差分隐私(gaussian 确定性噪声、RDP 抽样高斯、`GaussianAccountant`);`cargo test -p nax-fl` 全绿(7 测:裁剪/置零/均值/RDP golden、记账 golden、噪声统计与确定性、聚合链行为)。复用 `nax-core::prg::Stream` 做确定性高斯,零新依赖。
- **#3 横向 FedAvg(✅ 完成)**:在 `nax-fl` 内新增 `fedavg` / `linear` / `metrics` 三模块,对齐 `ml/fedavg.py` + `ml/aggregate.py` + `ml/linear.py` + `ml/metrics.py`。纯算法层:`local_train`(SGDP mini-batch)、`predict_proba`、`accuracy`/`auc`/`log_loss`、按样本数加权 `Mean`、FedAvg 责任链调度(`Δ 聚合`而非权重聚合)。`cargo test -p nax-fl` 现共 12 测全绿,其中 4 个逐位 golden(本地训练 / 指标 / 加权均值 / FedAvg 轨迹)。CLI 新增 `nax fl` 本地演示子命令(合成可分离数据、多轮打印 loss/acc/auc),直接补上"Python 示例覆盖"这一原始 gap。
- **#4 安全 MLP(✅ 完成)**:在 `nax-ml` 内新增 `mlp` 模块,对齐 `ml/mlp.py` 前向 / 反向数学。明文 f64 实现:He/Xavier 初始化(确定性 Box-Muller)、前向 `z = a@Wᵀ+b`、隐藏层 sigmoid/tanh、输出层固定 sigmoid、**复用与密文路径相同的奇多项式 sigmoid(`SIGMOID_FITS` degree 7)** 使训练轨迹与密文版一致;反向用解析导数、梯度按样本数平均。4 测全绿:3 个逐位 golden(固定权重下的前向概率 / 单步梯度 / 5 轮 loss 轨迹 + 最终权重)+ 1 个可分离数据收敛(acc > 0.9)。
- **#5 异构分箱(✅ 完成)**:在 `nax-ml` 内新增 `binning` 模块,对齐 `ml/binning.py` 纯算法层:切点计算(quantile 线性插值 / uniform / custom,`unique` + 严格 `(lo,hi)` 过滤)、`searchsorted(side=right)` 分箱、one-hot 指示矩阵、WOE/IV 与 **k-匿名 + 互补抑制**(Cox 1980,补完可发布箱 <2 则整列作废)。6 测全绿,切点 / 分箱 / WOE-IV 均逐位对照。分布式外壳(`VFrame`/`Site`/`Vault` 密文 `Mᵀ@y`)复用既有原语。
- **#6 数据层(✅ 完成)**:新建 `nax-data` crate,对齐 `data/{frame,stats,mock}.py` 本地算法层:列主序 `Frame`(构造/选择/丢弃/取矩阵/列和/列平方和)、明文统计(均值/总体方差/协方差/皮尔逊/相关矩阵)、mock(确定性主键 `mock_id_`、`overlap_offset=round(n(1-overlap))`、schema 合成、DP 边缘统计)、极简数值 CSV 读写。16 测全绿。分布式外壳(`VFrame.psi_align`/`Dataset.load` 的 dry_run 切换)复用既有原语。
- **#7 SCQL SQL 引擎(✅ 完成)**:新建 `nax-sql` crate,对齐 `sql/{ast,parser,engine}.py`。手写词法 + 递归下降解析(不支持 UNION/LIKE/DISTINCT/除法/外连接/窗口/子查询等,词法阶段即报错);明文执行语义:WHERE 求值成 0/1 **掩码**(非物理过滤)、AND/OR/NOT 位运算、聚合乘掩码(COUNT/SUM/AVG/MIN/MAX)、GROUP BY 依赖公开取值域、k-匿名抑制(无 GROUP BY 时报错)、CCL 投影约束(拒绝裸机密列)、等值内连接、HAVING/ORDER BY/LIMIT 明文后处理。15 测全绿。
- **#8 策略/审计/守卫(✅ 完成)**:新建 `nax-policy` crate,对齐 `policy/{audit,guard}.py`。`Label` 六档(plain/share/cipher/masked/public/released)+ MOVABLE/FETCHABLE 集合;`AuditEvent`/`AuditLog`(record/filter/summary/dump/clear,超上限裁半);`Guard` 三关口(check_exec / check_transfer / check_fetch,协议内部 `internal` 豁免,拒绝即记 denied 事件并返回 `PrivacyViolation`)。9 测全绿。
- **#9 dry_run 模式(✅ 完成)**:新建 `nax-runtime` crate,对齐 `runtime/mode.py`。线程局部 `DRY_RUN`/`DRY_HOST`/`DRY_FXP` + RAII guard(`dry_run(host, emulate_fixed_point)` / `real_run()`),drop 恢复上一层状态,支持嵌套与并发隔离。4 测全绿(默认、进入/退出、嵌套恢复、real_run 临时覆盖)。
- **9 个优先块全部完成**:Python 参考里约 46% 未 port 的算法层已补齐,`cargo test --workspace` 212 测全绿。
## 集成层(第一刀:安全 FedAvg)
明文层验证的是**语义正确性**;集成层验证它确实能跑在密态算子上。先挑依赖最少的一块:
- **`nax-fl` 加可选 `secure` feature**(拉 `nax-vault`,默认关闭,保持明文层零密码学依赖):`secure::weighted_mean_shares` 用 `mul_trunc`(Beaver 乘 + 定点截断)+ `add_local` + `reveal`(打开公开的总样本数)+ `scale_public`(1/Σn) + `truncate` 计算 `ΣnᵢΔᵢ/Σnᵢ`,**不需要安全比较**。
- 2 方 in-process 端到端测试(`Pipe::pair()` 双线程)对着明文 `weighted_mean` 验证,`cargo test -p nax-fl --features secure` 13 测全绿。误差落在定点精度理论上界 `(|ΣnΔ|+1)·2^-fxp` 内。
- 为什么先做 FedAvg 而不是 SQL/分箱:后两者依赖 `_bit_lt`/`_bit_eq`(交互式 BitLT),`nax-vault` 当时没有安全比较。
## 集成层第二刀:安全比较(`nax-vault::compare`)
给 `nax-vault` 补上 `edaBit` + BitLT + 原始 0/1 位代数,逐位对齐 `device/vault.py`:
- `edabit(len)`:从 `Dealer` 取本方 64 个共享比特(布局 `[bit*len+i]`)。
- `msb_raw(x)`:edaBit → `pack` 出 r → 打开 `c = x + r` → `unpack` 拆 c 的比特 → `borrow = [c_low < r_low]`(63 位 BitLT)→ `msb = (c₆₃ ⊕ r₆₃) ⊕ borrow`。
- `bit_lt_public`(内部):`d = a⊕b` → 后缀积扫描(Hillis–Steele,**乘法走 Beaver**)→ `z = p·d` → `Σ z·(1−a)`。
- 对外:`bit_lt`/`bit_gt`/`bit_eq`/`bit_not`/`bit_and`/`bit_or`/`bit_xor`/`bit_mask`/`select_raw`;`bit_one`/`bit_zero`。
- **关键坑:公开常量只在 0 号加一次**。`nax-core::compare::xor_bits_into` / `not_bits_into` 把常量加到了每一方,2 方重建时会翻倍(正是铁律「公开值只能出现一次」)。所以本模块改用自带的 `lin_bits`(`out_p = coef·b_p + (c if p==0 else 0)`),并在 `msb` 里把 `t·borrow` 交给 Beaver(`nax-core::msb_combine_into` 的本地 `mul_into` 对分片不成立)。
- 15 测全绿(10 原有 + 5 新):`bit_lt`/`bit_eq`/`bit_mask`/`select_raw` 对照明文、`msb` 符号、布尔代数真值表、64 组随机化对拍(含 ±0/相等/跨零/同号大值)、`SUM(x) WHERE x<T` 端到端。
## 集成层第三刀:SQL 掩码 WHERE 与分箱 `Mᵀ@y`(密态执行)
把明文引擎的核心语义搬到真实分片上,跑 2 方 in-process 会话对拍明文:
- **`nax-sql` 加可选 `secure` feature**:`secure::secure_where_aggregate` 实现
`SELECT <COUNT/SUM/AVG/MIN/MAX> FROM t WHERE col <op> T`:掩码 = `bit_lt/gt/eq` → `bit_mask` → 本地线性求和/`scale_public`+`truncate`;MIN/MAX 用 `(1−mask)·(±SENTINEL)` 本地补位后两两 `bit_lt`+`select_raw` 归约。
`secure::secure_group_by`:逐**公开码** c 做 `bit_eq(gcol, c)` 与 WHERE 掩码 AND,再走同一聚合核心。阈值/组码用 `nax-vault::constant`(公开常量分片 `(c,0,…)`),无需调用方 split。
`secure::secure_predicate_mask` + `Pred`:复合谓词(AND/OR/NOT 组合比较)走 `bit_and/or/not`;`Pred::In` 脱糖成 OR 等式(可 negated)。6 测对拍明文 `Engine`(WHERE+聚合、空命中 NaN、GROUP BY、k-匿名、复合谓词 AND/OR/NOT、IN/NOT IN)。
- **`nax-ml::binning_secure`**:`secure_bin_counts` 实现 `bad = Mᵀ·y`(`matmul_trunc`,转置为本地置换)+ `total`(本地列和)。1 测对拍明文 `Mᵀ@y` / `Mᵀ@1`。`nax-ml` 已硬依赖 `nax-vault`,无需 feature。
- 尺度约定:one-hot 与标签都按 fxp 编码(`1 → 2^fxp`),`Mᵀ@y` 落在 `2·fxp`,`matmul_trunc` 截回 `fxp`;`total` 线性列和天然 `fxp`。
- **CLI 端到端演示**:`nax sql`(编译需 `--features secure`)在单进程内用两条 `Pipe` 起 2 方,真跑一遍 `GROUP BY + COUNT/SUM/AVG`,打印结果表——从二进制直接看到密态 SQL 生效。
- 现状:`cargo test --workspace` 218 测;`-p nax-sql --features secure` 21 测、`-p nax-fl --features secure` 13 测、`-p nax-ml` 15 测,全绿、零警告。