Files
ssw-mpc/crates/mpc-sql/src/secure_graph.rs
T
admin 54781b3f83
ci / gate (push) Waiting to run
refactor: 项目改名 ssw-mpc,crate 统一到 mpc-* 前缀
- 项目与文档标题:nax-rs → ssw-mpc(尚数网-多方安全计算),二进制 nax → mpc
- 18 个 crate 及目录 nax-* → mpc-*,Rust 引用 nax_* → mpc_*
- 环境变量、C 符号、构建/部署脚本:NAX_* → MPC_*、libnax_ray.so → libmpc_ray.so
- 保留协议域分隔常量与 refs/nax 参考实现路径,维持 golden 向量与历史数据兼容
- 新增 [profile.dev] incremental=false
2026-11-05 15:06:12 +08:00

670 lines
26 KiB
Rust
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.
//! 掩码 WHERE + 聚合的**算子图**实现。
//!
//! 迁移前,这条路径是 `secure.rs` 里一串手写的 `vault.*` 调用:先 `bit_lt`,
//! 再 `bit_mask`,再 `mul`,再 `scale_public` + `truncate` …… 每写一行都要同时
//! 回答两个问题 —— 「数学上算什么」和「这一步要不要过网络」。漏一次 `truncate`
//! 的结果不是崩溃,是**数值差 2^fxp 倍且不报错**。
//!
//! 迁移后是同一条语义的图:
//!
//! ```text
//! 谓词 → 0/1 位 → 掩码 → 掩码后列 → 各聚合 → open
//! ```
//!
//! 由此换来两件以前做不到的事:
//!
//! 1. **轮数能报出来**。`Plan::rounds()` 给出一条查询的往返数,不再靠人数代码里
//! 出现了几次 `bit_lt`、几次 `bit_mask`。
//! 2. **尺度由构造期检查**。`scale_public` 之后忘了 `truncate` 就相加,建图当场
//! 报「定点尺度不一致」,而不是算出一个差 2^fxp 倍的数。
//!
//! # 为什么分成两段图
//!
//! `AVG = SUM / COUNT`,而除数 `COUNT` 本身**就是要公开的**(`AVG` 的输出是它
//! 唯一的信息,`k`-匿名抑制也要用它)。所以第一段图只做「掩码后列 + 命中数」,
//! 把 `COUNT` open 出来;第二段图拿到 `1/count` 之后再建,除数就退化成普通的
//! 公开系数。
//!
//! 这不是为了迁就 IR —— 迁移前的参考实现也是**先 reveal count、再算其余聚合**,
//! 两段的协议形状完全一致。差别只在:第二段图里 `SUM` / `MIN` / `MAX` 的 `open`
//! 落在同一阶段,会**合成一次往返**;参考实现是逐个 `reveal`,串行。
//!
//! 实测(5 行、`[COUNT, SUM, AVG, MIN, MAX]`、`col < 300`):迁移前 96 轮,
//! 迁移后 95 轮。省下的就是那几次合并 —— 搬家的目的不是提速,是让轮数可报、
//! 让尺度错误在建图期就暴露。
//!
//! 没有 `AVG` 时第二段图是空的,直接不建 —— 这时 `COUNT` 的 `open` 和其余聚合的
//! `open` 仍然分属两段,比理论最优多一轮。**这是已知的、刻意保留的保守**:把两段
//! 合成一段要求「第二段不依赖第一段的输出」,而 `AVG` 请求存在时它恰好不成立,
//! 为一个可选优化维护两条建图路径不划算。写在文档里比藏在代码里好。
//!
//! # 分组
//!
//! `GROUP BY` 有两条建图路径,语义相同、协议形状不同,由
//! [`crate::secure::GroupMode`] 选:
//!
//! **逐组比较(`Exact`,默认)**:每个组是一个独立分支,全部塞进**同一张图**。
//! 各组掩码互不依赖,于是各组的 `open` 合到同一轮 —— 迁移前是逐组串行,`N` 个组
//! 就是 `2N` 次 `reveal`,现在只要 2 次。省下 `2N − 2` 轮(8~9%),**不是数量级**:
//! 主导成本是每组的 `bit_eq`(两次比较 = 18 轮),它按组累加。
//!
//! **整数分组码前缀和(`IntegerCode`,`--group-mode coded`)**:把「`N` 个组的
//! 相等判断」换成「`N+1` 个单调前缀 `码 ≤ g`」,组内值由累积和相减得到,全程只有
//! 一次批量 `open`、**没有第二段图**。实测(`--rows 8 --aggs count,sum`):
//!
//! | 组数 | Exact | IntegerCode |
//! |---|---|---|
//! | 2 | 42 | 32 |
//! | 4 | 82 | 52 |
//! | 8 | 162 | **92** |
//!
//! 每组的建图成本从 20 轮降到约 11 轮(`9` 一次比较 + `2` 一次掩码乘)。
//! 代价是两条**契约**(密态下无法校验,由调用方保证):分组码必须是整数、
//! 且不支持 `MIN`/`MAX`(分组极值不能由前缀和还原)。见
//! [`crate::secure::GroupMode::IntegerCode`] 与 `tests/coded.rs`。
//!
//! WHERE 未命中的行不逐组乘 `base`,而是**把码搬到 −1000**:这些行会出现在
//! 每一个前缀里,差分时自动抵消,省掉 `2N` 轮。搬迁值必须按 `2^fxp` 缩放 ——
//! 第一版拿真值 `−1000` 当 raw 用,它比 `0.5·2^18` 还大,被算进了每一个前缀,
//! 行数变成全表。**尺度不统一不会报错,只会算错。**
//!
//! # 命中数为 0 的分支
//!
//! 迁移前的实现 `count == 0` 时直接返回 `NaN`,连归约都不跑。这里保留这个语义,
//! 但位置变了:`count` 在第一段图之后才知道,所以第二段图**建的时候就跳过**该分支
//! 的 `MIN` / `MAX` 子图(返回 [`AggOut::Empty`]),省掉 `10·(len−1)` 轮。
use mpc_ir::{run, CmpKind, Graph, IrError, Plan, Shape, Val};
use mpc_vault::{Transport, Vault, VaultError};
use crate::secure::{Agg, CmpOp, Pred};
/// IR 错误 → `VaultError`。密态路径上的错误本来就是参数/协议类。
pub(crate) fn ir(e: IrError) -> VaultError {
VaultError::Protocol(e.to_string())
}
fn col_shape(len: usize) -> Shape {
Shape::vec(len)
}
/// 一个聚合分支的结果去向。
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
pub(crate) enum AggOut {
/// 第一段图里已经拿到(`COUNT` 明文)。
Known,
/// 明文值在这个节点上,`open` 过了。
Val(Val),
/// 没建子图:命中数为 0,按语义结果是 `NaN`。
Empty,
}
/// 第一段图的一个分支:掩码后列、命中数、以及 MIN/MAX 的补位值。
#[derive(Clone, Copy, Debug)]
pub(crate) struct BranchOut {
/// `mask · col`(精确乘,未截断)。
pub masked: Val,
/// 已 `open` 的命中数(原始整数,不是 fxp)。
pub count: Val,
/// `(1 − mask) · +SENTINEL`,未请求 MIN 时为 `None`。
pub min_pad: Option<Val>,
/// `(1 − mask) · −SENTINEL`,未请求 MAX 时为 `None`。
pub max_pad: Option<Val>,
}
/// 第一段图:掩码 + 掩码后列 + 命中数。
pub(crate) struct CountStage {
/// 编译好的计划。
pub plan: Plan,
/// 每分支的输出节点,与建图时的分支顺序一致。
pub branches: Vec<BranchOut>,
}
/// 第二段图的输入从哪来:第一段图的哪个输出。
#[derive(Clone, Copy, Debug)]
pub(crate) enum Feed {
/// 第几分支的掩码后列。
Masked(usize),
/// 第几分支的 MIN 补位值。
MinPad(usize),
/// 第几分支的 MAX 补位值。
MaxPad(usize),
}
/// 第二段图:除 `COUNT` 外的聚合。
pub(crate) struct AggStage {
/// 编译好的计划。
pub plan: Plan,
/// `outs[分支][agg]`,与建图时给的 `aggs` 对齐。
pub outs: Vec<Vec<AggOut>>,
/// 要喂进图的输入,按 slot 顺序。
pub feeds: Vec<Feed>,
}
/// 建图上下文:一次查询里行数与 fxp 固定。
#[derive(Clone, Copy)]
pub(crate) struct Ctx {
/// 行数。
pub len: usize,
/// 定点小数位数。
pub fxp: u32,
}
impl Ctx {
/// 显式构造。
pub fn new(len: usize, fxp: u32) -> Self {
Self { len, fxp }
}
fn shape(&self) -> Shape {
col_shape(self.len)
}
/// 公开阈值(按 fxp 编码)。
fn threshold(&self, g: &mut Graph, v: f64) -> Result<Val, IrError> {
g.constant_f64(self.fxp, &vec![v; self.len], self.shape())
}
/// 原始 0/1 常量 —— `Vault::bit_one` 的图版本。
///
/// 注意这里是 `constant`(raw 值直给)而不是 `constant_f64`:后者编出来是
/// fxp 的 `1.0`(raw = 2^fxp),拿去当位掩码会让所有值差 2^fxp 倍。
pub fn ones(&self, g: &mut Graph) -> Result<Val, IrError> {
g.constant(vec![1u64; self.len], self.shape())
}
/// `CmpOp` → 共享 0/1 位。
pub(crate) fn compare(&self, g: &mut Graph, op: CmpOp, a: Val, b: Val) -> Result<Val, IrError> {
Ok(match op {
CmpOp::Lt => g.cmp(CmpKind::Lt, a, b)?,
CmpOp::Gt => g.cmp(CmpKind::Gt, a, b)?,
CmpOp::Eq => g.cmp_eq(a, b)?,
CmpOp::Le => g.cmp_le(a, b)?,
CmpOp::Ge => g.cmp_ge(a, b)?,
CmpOp::Ne => g.cmp_ne(a, b)?,
})
}
/// `col <op> 公开阈值` → 共享 0/1 位。
pub(crate) fn mask_cmp(
&self,
g: &mut Graph,
col: Val,
value: f64,
op: CmpOp,
) -> Result<Val, IrError> {
let th = self.threshold(g, value)?;
self.compare(g, op, col, th)
}
/// `a AND b`:一次精确乘(`Vault::bit_and` 就是 `mul`)。
pub(crate) fn and(&self, g: &mut Graph, a: Val, b: Val) -> Result<Val, IrError> {
g.mul_raw(a, b)
}
/// `a OR b = a + b − a·b`。
fn or(&self, g: &mut Graph, a: Val, b: Val) -> Result<Val, IrError> {
let ab = g.mul_raw(a, b)?;
let s = g.add(a, b)?;
g.sub(s, ab)
}
/// 复合谓词 → 共享 0/1 位。
///
/// 与迁移前的 `secure_predicate_mask` 一一对应:`Cmp` 走一次比较,`CmpCol`
/// 两侧都是分片(**不过** `threshold`,那等于把比较基准告诉对端),`In`
/// 脱糖成若干 `=` 的 OR,`And`/`Or`/`Not` 用位代数。
pub fn pred(&self, g: &mut Graph, cols: &[Val], p: &Pred) -> Result<Val, IrError> {
match p {
Pred::Cmp { col, op, threshold } => {
let c = self.col(cols, *col, "谓词引用了不存在的列")?;
let th = self.threshold(g, *threshold)?;
self.compare(g, *op, c, th)
}
Pred::CmpCol { col, op, rhs_col } => {
if col == rhs_col {
return Err(IrError::Op(format!(
"列与自身比较(列 {col})—— 语义上恒定,多半是写错了"
)));
}
let a = self.col(cols, *col, "谓词引用了不存在的列")?;
let b = self.col(cols, *rhs_col, "谓词右值引用了不存在的列")?;
self.compare(g, *op, a, b)
}
Pred::In {
col,
values,
negated,
} => {
let c = self.col(cols, *col, "谓词引用了不存在的列")?;
if values.is_empty() {
return Err(IrError::Op("IN 列表为空".into()));
}
let mut acc: Option<Val> = None;
for &v in values {
let th = self.threshold(g, v)?;
let eq = g.cmp_eq(c, th)?;
acc = Some(match acc {
None => eq,
Some(prev) => self.or(g, prev, eq)?,
});
}
let m = acc.expect("上面刚判过非空");
Ok(if *negated { g.bit_not(m) } else { m })
}
Pred::And(a, b) => {
let ma = self.pred(g, cols, a)?;
let mb = self.pred(g, cols, b)?;
self.and(g, ma, mb)
}
Pred::Or(a, b) => {
let ma = self.pred(g, cols, a)?;
let mb = self.pred(g, cols, b)?;
self.or(g, ma, mb)
}
Pred::Not(a) => {
let m = self.pred(g, cols, a)?;
Ok(g.bit_not(m))
}
}
}
/// 分组码相等:`gcol == code` 的 0/1 位。
pub(crate) fn group_code(&self, g: &mut Graph, gcol: Val, code: usize) -> Result<Val, IrError> {
let c = self.threshold(g, code as f64)?;
g.cmp_eq(gcol, c)
}
fn col(&self, cols: &[Val], i: usize, what: &str) -> Result<Val, IrError> {
cols.get(i)
.copied()
.ok_or_else(|| IrError::Op(format!("{what} {i}")))
}
}
// ── 第一段:掩码 + 掩码后列 + 命中数 ─────────────────────────────────── //
/// 建第一段图。
///
/// `cols` 是声明的输入列数;`masks` 拿到这些输入节点后返回每分支的掩码。
/// 分支数 = `masks` 返回的个数(`GROUP BY` 时 = 组数)。
pub(crate) fn build_count_stage<F>(
ctx: Ctx,
cols: usize,
agg_col: usize,
aggs: &[Agg],
masks: F,
) -> Result<CountStage, VaultError>
where
F: FnOnce(&mut Graph, &[Val]) -> Result<Vec<Val>, IrError>,
{
if cols == 0 {
return Err(VaultError::Protocol("至少要有一列".into()));
}
if agg_col >= cols {
return Err(VaultError::Protocol(format!("聚合列 {agg_col} 不存在")));
}
let mut g = Graph::new();
let inputs: Vec<Val> = (0..cols).map(|_| g.input(col_shape(ctx.len))).collect();
let mask_vals = masks(&mut g, &inputs).map_err(ir)?;
if mask_vals.is_empty() {
return Err(VaultError::Protocol("没有要聚合的分支".into()));
}
let col = inputs[agg_col];
let want_min = aggs.contains(&Agg::Min);
let want_max = aggs.contains(&Agg::Max);
let mut branches = Vec::with_capacity(mask_vals.len());
for mask in mask_vals {
// 命中行留原值、未命中变 0。精确乘,无截断。
let masked = g.mul_raw(mask, col).map_err(ir)?;
// MIN/MAX 的补位:`(1−mask)·±SENTINEL`。这是**本地**算术 ——
// `1−mask` 是位取反,乘常数走裸整数乘,都不花往返。
//
// 掩码是公开的全 1(无 WHERE 的整表聚合)时 `1−mask ≡ 0`,补位是空操作:
// 不算,也就不会撞上 `scale_int` 拒公开值那条。
let pad = |g: &mut Graph, sign: i64| -> Result<Option<Val>, IrError> {
if g.vis(mask).is_public() {
return Ok(None);
}
let not_m = g.bit_not(mask);
let k = sentinel_scale(ctx.fxp, sign)?;
Ok(Some(g.scale_int(not_m, k)?))
};
let min_pad = if want_min {
pad(&mut g, 1).map_err(ir)?
} else {
None
};
let max_pad = if want_max {
pad(&mut g, -1).map_err(ir)?
} else {
None
};
// COUNT:本地列和 → open。掩码公开时列和也公开,`open` 是空操作(0 轮)。
let csum = g.sum(mask);
let count = g.open(csum);
branches.push(BranchOut {
masked,
count,
min_pad,
max_pad,
});
}
let plan = Plan::compile(g).map_err(ir)?;
Ok(CountStage { plan, branches })
}
/// `−PARKED_CODE` 的 raw 编码(即 `−PARKED_CODE · 2^fxp`)。
///
/// 一个 i64 装得下:`1000 · 2^40 ≈ 1.1e15`,离 `i64::MAX` 还有三个数量级。
fn parked_raw(fxp: u32) -> Result<i64, IrError> {
if fxp > 40 {
return Err(IrError::Op(format!(
"fxp={fxp} 太大:整数分组码的停放值 −{PARKED_CODE}·2^{fxp} 会溢出 i64"
)));
}
Ok(-(PARKED_CODE << fxp))
}
/// `±SENTINEL` 的 fxp 编码,作为 `scale_int` 的整数系数。
///
/// 哨兵取 `2^30`:远大于常规业务值(几十万就到顶了),又远小于定点溢出上限。
/// 要的是 `(1−mask)·SENTINEL·2^fxp`(即 `SENTINEL` 在 fxp 尺度上的编码),
/// 所以系数是 `SENTINEL << fxp`。迁移前这一步是 `scale_public(x, ±SENTINEL)`,
/// 编出来的值就是这个 —— 同一条环乘法,只是不走协议。
fn sentinel_scale(fxp: u32, sign: i64) -> Result<i64, IrError> {
let bits = 30u32 + fxp;
if bits >= 63 {
return Err(IrError::Op(format!(
"fxp={fxp} 太大:MIN/MAX 的补位哨兵 2^{bits} 会溢出 i64"
)));
}
Ok(sign * (1i64 << bits))
}
// ── 第二段:除 COUNT 外的聚合 ───────────────────────────────────────── //
/// 建第二段图。`counts[i]` 是第 i 分支的命中数,必须与 `first` 等长。
pub(crate) fn build_agg_stage(
ctx: Ctx,
aggs: &[Agg],
first: &[BranchOut],
counts: &[usize],
) -> Result<AggStage, VaultError> {
if counts.len() != first.len() {
return Err(VaultError::Protocol(format!(
"有 {} 个分支却有 {} 个命中数",
first.len(),
counts.len()
)));
}
let mut g = Graph::new();
let mut feeds = Vec::new();
let mut inputs: Vec<(Val, Option<Val>, Option<Val>)> = Vec::with_capacity(first.len());
for (i, b) in first.iter().enumerate() {
// 输入按「每分支 [掩码后列, MIN 补位?, MAX 补位?]」声明,
// 顺序与 `feeds` 一致 —— 调用方按 feeds 喂。
let masked = g.input(col_shape(ctx.len));
feeds.push(Feed::Masked(i));
let min_pad = if b.min_pad.is_some() {
feeds.push(Feed::MinPad(i));
Some(g.input(col_shape(ctx.len)))
} else {
None
};
let max_pad = if b.max_pad.is_some() {
feeds.push(Feed::MaxPad(i));
Some(g.input(col_shape(ctx.len)))
} else {
None
};
inputs.push((masked, min_pad, max_pad));
}
let mut outs = Vec::with_capacity(first.len());
for (i, _b) in first.iter().enumerate() {
let (masked_in, min_in, max_in) = inputs[i];
let count = counts[i];
let mut row = Vec::with_capacity(aggs.len());
for &agg in aggs {
row.push(match agg {
Agg::Count => AggOut::Known,
// SUM 对空选择有定义(= 0),所以排在下面那条 NaN 规则之前。
Agg::Sum => {
let s = g.sum(masked_in);
AggOut::Val(g.open(s))
}
// AVG / MIN / MAX 在空选择下没有定义。参考实现直接给 NaN、连算都
// 不算 —— 图是固定形状的,所以「不算」要在**建图时**决定:命中数
// 是上一段 open 出来的,这里已经知道了。
Agg::Avg | Agg::Min | Agg::Max if count == 0 => AggOut::Empty,
Agg::Avg => {
let s = g.sum(masked_in);
// 除数已公开:`scale` 编系数、乘完截断,与迁移前的
// `scale_public` + `truncate` 是同一条序列。
let scaled = g.scale(s, 1.0 / count as f64).map_err(ir)?;
AggOut::Val(g.open(scaled))
}
Agg::Min => AggOut::Val(minmax(&mut g, ctx.len, min_in, masked_in, true).map_err(ir)?),
Agg::Max => {
AggOut::Val(minmax(&mut g, ctx.len, max_in, masked_in, false).map_err(ir)?)
}
});
}
outs.push(row);
}
let plan = Plan::compile(g).map_err(ir)?;
Ok(AggStage { plan, outs, feeds })
}
/// 逐行归约:`best = min/max(padded[0..len])`,**树形**,不是线性扫描。
///
/// # 为什么树形划算(这里原先写反了)
///
/// 第一版照抄迁移前的手写循环:`best` 依次与每一行比一次、选一次。当时的注释说
/// 「树形不省轮数,因为串行依赖不变」—— **错的**。串行依赖的深度不一样:
///
/// | 归约方式 | 依赖深度 | `len` 行需要的往返 |
/// |---|---|---|
/// | 线性扫描 | `len − 1` | `(len−1) × (CMP_ROUNDS + 1)` |
/// | 树形 | `⌈log₂ len⌉` | `⌈log₂ len⌉ × (CMP_ROUNDS + 1)` |
///
/// 关键在于**同一层的比较互不依赖**,于是它们落进同一个阶段、合成一批
/// (`bit_lt_batch` 让 k 次比较 9 轮封顶)。线性链每一层只有一个比较,批不起来;
/// 树形第 `i` 层有 `⌈len/2^i⌉` 个比较,一起发。5 行从 4 层降到 3 层,
/// 100 行从 99 层降到 7 层。
///
/// 结合律上没问题:`min` / `max` 都可结合,且这里只有 `cmp` + `select`,
/// 没有截断,换结合顺序**不引入任何数值差**。
///
/// 奇数个元素时最后一个直接轮空进下一层(不是补一个哑元素)—— 补哑元素要
/// 多一次比较,轮空免费。
fn minmax(
g: &mut Graph,
len: usize,
pad: Option<Val>,
masked: Val,
min: bool,
) -> Result<Val, IrError> {
if len == 0 {
return Err(IrError::Shape("MIN/MAX 至少要一行".into()));
}
let padded = match pad {
Some(p) => g.add(masked, p)?,
None => masked,
};
// 叶子层:每行一个 1 元向量(本地切片,零通信)。
let mut level: Vec<Val> = (0..len)
.map(|i| g.slice(padded, i, 1))
.collect::<Result<_, _>>()?;
// 逐层两两归约。每层里所有比较互不依赖 → 同一阶段 → 一批。
while level.len() > 1 {
let mut next: Vec<Val> = Vec::with_capacity(level.len().div_ceil(2));
let mut i = 0;
while i + 1 < level.len() {
let (a, b) = (level[i], level[i + 1]);
let cond = if min {
g.cmp(CmpKind::Lt, b, a)?
} else {
g.cmp(CmpKind::Lt, a, b)?
};
next.push(g.select(cond, b, a)?);
i += 2;
}
if i < level.len() {
next.push(level[i]);
}
level = next;
}
Ok(g.open(level[0]))
}
// ── 整数分组码:前缀段 ───────────────────────────────────────────────── //
/// WHERE 未命中的行,分组码被搬到 `−PARKED_CODE` 上(远小于任何合法码)。
///
/// 为什么要「搬码」而不是逐组再乘一次 `base`:前缀和天然会**抵消** —— 这些行
/// 出现在**每一个**前缀集合里,任意两个前缀相减时它们就被减掉了。于是每组的
/// 建图不用再乘一次 `base`,省下 `2N` 轮。
///
/// 注意这是**真值**,要乘 `2^fxp` 才是 raw 值:分组码列是 fxp 编码的,
/// 边界 `g+0.5` 编出来是 `(g+0.5)·2^fxp`。第一版直接拿 `−1000` 当 raw 起步,
/// 结果它比 `0.5·2^18` 还大,被算进了每一个前缀 —— 行数变成全表,`SUM` 也跟着
/// 变成全表之和。**尺度不统一不会报错,只会算错。**
const PARKED_CODE: i64 = 1000;
/// 整数分组码的前缀段:`N+1` 个单调前缀,各组的值由累积和差分得到。
///
/// 与 [`CountStage`] 的区别是**没有「每分支一份掩码」**:这里只有前缀,
/// 组内值在明文侧相减。因此它不需要第二段图 —— 所有输出在一次批量 `open`
/// 里就都是公开的了。
pub(crate) struct PrefixStage {
/// 编译好的计划。
pub plan: Plan,
/// `cum_count[i]` = 码 `≤ i−1` 的行数(已 open,原始整数)。`i ∈ 0..=N`。
pub cum_count: Vec<Val>,
/// `cum_sum[i]` = 码 `≤ i−1` 的列和(已 open,fxp 原始值)。`i ∈ 0..=N`。
pub cum_sum: Vec<Val>,
}
/// 建前缀段图。
///
/// `code_col` 是分组码在输入里的下标、`agg_col` 是聚合列的下标。
/// `base_of` 返回 WHERE 掩码;返回 `None` 表示没有 WHERE(掩码是公开全 1)。
///
/// # 为什么是 `N+1` 个边界
///
/// 组的边界在 `g + 0.5`(`g = −1 ..= N−1`):`码 < g + 0.5` 等价于 `码 ≤ g`,
/// 且对**整数**码没有歧义。两端的 `−1` / `N−1` 不是多余的 —— 有它们,
/// 越界码(负数、`≥ N`)会自然落在所有分组之外,与逐组 `==` 的语义一致。
///
/// # 为什么要求 `fxp ≥ 1`
///
/// `g + 0.5` 要能被定点表示。`fxp == 0` 时它会被舍成整数,边界全错一位且
/// **不报错**,所以这里直接拒。
pub(crate) fn build_prefix_stage<F>(
ctx: Ctx,
cols: usize,
agg_col: usize,
code_col: usize,
n_groups: usize,
base_of: F,
) -> Result<PrefixStage, VaultError>
where
F: FnOnce(&mut Graph, &[Val]) -> Result<Option<Val>, IrError>,
{
if cols == 0 || agg_col >= cols || code_col >= cols {
return Err(VaultError::Protocol(format!(
"前缀段:列下标越界(cols={cols}, agg={agg_col}, code={code_col})"
)));
}
if n_groups == 0 {
return Err(VaultError::Protocol("分组数必须大于 0".into()));
}
if ctx.fxp == 0 {
return Err(VaultError::Protocol(
"整数分组码要求 fxp ≥ 1(边界取 g+0.5,fxp=0 会把它舍掉)".into(),
));
}
let mut g = Graph::new();
let inputs: Vec<Val> = (0..cols).map(|_| g.input(col_shape(ctx.len))).collect();
let col = inputs[agg_col];
let code = inputs[code_col];
let base = match base_of(&mut g, &inputs).map_err(ir)? {
Some(m) => m,
None => ctx.ones(&mut g).map_err(ir)?,
};
// WHERE 未命中 → 码搬到 −1000。`base·code + (1−base)·(−1000)`:
// 前一项要一次 Beaver 乘(2 轮),后一项是裸整数乘(0 轮)。
let code_w = if g.vis(base).is_public() {
code
} else {
let kept = g.mul_raw(base, code).map_err(ir)?;
let not_base = g.bit_not(base);
let park = parked_raw(ctx.fxp).map_err(ir)?;
let off = g.scale_int(not_base, park).map_err(ir)?;
g.add(kept, off).map_err(ir)?
};
let mut prefixes = Vec::with_capacity(n_groups + 1);
for i in 0..=n_groups {
// 第 i 个前缀 = 码 ≤ i−1 = 码 < (i−1) + 0.5
let th = ctx.threshold(&mut g, i as f64 - 0.5).map_err(ir)?;
prefixes.push(g.cmp(CmpKind::Lt, code_w, th).map_err(ir)?);
}
let mut cum_count = Vec::with_capacity(n_groups + 1);
let mut cum_sum = Vec::with_capacity(n_groups + 1);
for c in prefixes {
let cnt = g.sum(c);
cum_count.push(g.open(cnt));
let masked = g.mul_raw(c, col).map_err(ir)?;
let s = g.sum(masked);
cum_sum.push(g.open(s));
}
let plan = Plan::compile(g).map_err(ir)?;
Ok(PrefixStage {
plan,
cum_count,
cum_sum,
})
}
// ── 掩码单独出口(`mask_for` / `secure_predicate_mask`) ─────────────── //
/// 只算掩码:`cols` 个输入,返回掩码分片。
///
/// 这两个函数是对外 API 的一部分(调用方拿掩码自己用),所以它们不走两段式,
/// 就是一串「谓词 → 0/1 位」的图。
pub(crate) fn run_mask_only<T, F>(
vault: &mut Vault<T>,
ctx: Ctx,
given: &[&[u64]],
build: F,
) -> Result<Vec<u64>, VaultError>
where
T: Transport,
F: FnOnce(&mut Graph, &[Val]) -> Result<Val, IrError>,
{
let mut g = Graph::new();
let inputs: Vec<Val> = given.iter().map(|_| g.input(col_shape(ctx.len))).collect();
let mask = build(&mut g, &inputs).map_err(ir)?;
let plan = Plan::compile(g).map_err(ir)?;
let vals = run(&plan, vault, given, ctx.fxp).map_err(ir)?;
Ok(vals.get(mask).to_vec())
}