v0.41.74: HP-03 filter semantics and registration validation

Signed-off-by: Eli Ma <eli@patch.sh>

Author: genedna

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "mega2"
-version = "0.41.73"
+version = "0.41.74"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 description = "Monorepo engine and Git hosting server for AI agents: trunk-based storage, Git Smart HTTP, Git LFS, OCI registry, and Agent Session Capture"

Cargo.toml

@@ -1251,7 +1251,7 @@ fn mark_ready_if_covered(F, tip) -> bool:                           # 只在持
 - **过滤器规模上限【决策】。** 以下上限都是代码常量，不进配置；超限返回 400，并指明超了哪一项。它们只约束注册：worker 与 6.1 第 3 层加载已有定义时不复查，所以日后调低常量不会让已注册的视图失效。
   - `filter_spec` 经 JSON 解码后不超过 16 KiB（UTF-8 字节）；该路由另设 `DefaultBodyLimit::max(64 KiB)`。【代码】storage-only 的 `/api/v1` 没有单独的请求体上限，沿用 axum 默认的 2 MiB；`snapshot_router.rs` 约 L62、L76 以 `JSON_REQUEST_LIMIT = 131_072` 收紧，是先例。
   - `:[` 的嵌套层数不超过 16。解析器在递归下降时计数，超限立即报错，早于规范化与 pull 计算。【推断】不设此限时，2 MiB 的 `:[:[:[…` 会让递归实现在 tokio 工作线程上栈溢出，进程直接中止。
-  - 规范化后，全部 Compose 的成员总数不超过 64，Exclude 选择器总数不超过 256，`k = |src_paths(F)|` 不超过 64。k 决定三处开销：逐源路径授权的次数（本节与 5.2 B0）、2.7 授权面复核的选择器数、P2 锁内的 1 + k 次候选查询（5.2 第 7 步）。成员数决定每个提交 O(深度 × 成员数) 的脊柱 tree（3.5）。
+  - 规范化后，全部 Compose 的成员总数不超过 64，Exclude 选择器总数不超过 256。注册期以 `k = 64` 有界物化全过滤器与每个 Compose 成员的最小源路径集：活动集合超过 k 时立即以 K 超限拒绝（`actual = 65` 是下界），不为求最终 `|src_paths(F)|` 而继续展开；这一步早于尚未完成的 Compose 相交检查。于是每个获准过滤器都满足 `|src_paths(F)| ≤ k`，但某些最终会归约到 k 以内的输入也会被保守拒绝。k 决定三处开销：逐源路径授权的次数（本节与 5.2 B0）、2.7 授权面复核的选择器数、P2 锁内的 1 + k 次候选查询（5.2 第 7 步）。成员数决定每个提交 O(深度 × 成员数) 的脊柱 tree（3.5）。
   - 这组数值在 P0 基准中复核：用顶到上限的过滤器测单提交投影耗时与脊柱 tree 数，结果写入 7.2；超出预算就下调常量。
 - **解析栈安全上限（HP-02）。** `parse` 与 §2.1「往返要求」第 3 项的加载复核受栈安全上限 `PARSE_MAX_NESTING = 64` 约束：`:[` 嵌套超过它的定义行复核为 `DefinitionCorrupt { failed: RoundTrip }`，不会让 worker 或协议处理线程栈溢出；它不是本节规模上限，不在注册时施加，经注册写入的定义嵌套不超过当时的 `REGISTER_MAX_NESTING`（当前 16），复核不会因它失败；它只能调高，且不得低于历次发布的 `REGISTER_MAX_NESTING` 最大值（当前 16），调低会让已注册的定义失效，与本节「日后调低常量不会让已注册的视图失效」相悖，只能按 §2.4 升到 `v2` 或强制重建受影响的视图。
 - **注册准入【决策】。** 跨副本的计数与预留放在同一个 Postgres 短事务中，用 L_R（4.6）串行化。处理顺序为：规范化与 2.2 校验 → 逐源路径鉴权 → 准入事务。鉴权在准入之前，因此未通过鉴权的请求不会消耗任何 token 的配额。

docs/plan/plan-20261002.md

@@ -1,6 +1,9 @@
 mod canonical;
 mod parse;
 
+pub mod semantics;
+pub mod validate;
+
 pub use canonical::{canonicalize, print};
 use sha2::{Digest, Sha256};
 

docs/refactoring/history-projection.md

@@ -0,0 +1,262 @@
+use super::{Filter, canonicalize};
+
+pub fn invert(filter: &Filter) -> Filter {
+    let inverted = match filter {
+        Filter::Subdir(path) => Filter::Prefix(path.clone()),
+        Filter::Prefix(path) => Filter::Subdir(path.clone()),
+        Filter::Exclude(selectors) => Filter::Exclude(selectors.clone()),
+        Filter::Compose(members) => Filter::Compose(members.iter().map(invert).collect()),
+        Filter::Chain(ops) => Filter::Chain(ops.iter().rev().map(invert).collect()),
+        Filter::Nop => Filter::Nop,
+        Filter::Empty => Filter::Empty,
+    };
+    canonicalize(inverted)
+}
+
+/// Computes the exact source paths for a filter already accepted for registration.
+///
+/// Callers handling request-supplied filters must validate them before calling this
+/// function, because the exact result itself can be large for an unvalidated AST.
+pub fn src_paths(filter: &Filter) -> Vec<String> {
+    let mut paths = normalized_paths(pull(filter, vec![Vec::new()]))
+        .into_iter()
+        .map(|path| display_path(&path))
+        .collect::<Vec<_>>();
+    paths.sort();
+    paths
+}
+
+pub(crate) fn src_paths_limited(
+    filter: &Filter,
+    max_paths: usize,
+) -> Result<Vec<String>, SrcPathLimitExceeded> {
+    let paths = pull_limited(filter, vec![Vec::new()], max_paths)?;
+    let paths = normalized_paths(paths);
+    if paths.len() > max_paths {
+        return Err(SrcPathLimitExceeded);
+    }
+    let mut paths = paths
+        .into_iter()
+        .map(|path| display_path(&path))
+        .collect::<Vec<_>>();
+    paths.sort();
+    Ok(paths)
+}
+
+#[derive(Clone, Copy, Debug)]
+pub(crate) struct SrcPathLimitExceeded;
+
+fn normalized_paths(mut paths: Vec<Vec<String>>) -> Vec<Vec<String>> {
+    paths.sort();
+    paths.dedup();
+    let mut minimal: Vec<Vec<String>> = Vec::new();
+    for path in paths {
+        if !minimal.iter().any(|ancestor| is_prefix(ancestor, &path)) {
+            minimal.push(path);
+        }
+    }
+    minimal
+}
+
+fn pull_limited(
+    filter: &Filter,
+    paths: Vec<Vec<String>>,
+    max_paths: usize,
+) -> Result<Vec<Vec<String>>, SrcPathLimitExceeded> {
+    let paths = match filter {
+        Filter::Subdir(path) => paths
+            .into_iter()
+            .map(|suffix| join(path.segments(), &suffix))
+            .collect(),
+        Filter::Prefix(path) => paths
+            .into_iter()
+            .filter_map(|path_at_output| pull_prefix(path.segments(), &path_at_output))
+            .collect(),
+        Filter::Exclude(_) | Filter::Nop => paths,
+        Filter::Empty => Vec::new(),
+        Filter::Compose(members) => {
+            let mut output = Vec::new();
+            for member in members {
+                output.extend(pull_limited(member, paths.clone(), max_paths)?);
+                output = normalized_paths(output);
+                if output.len() > max_paths {
+                    return Err(SrcPathLimitExceeded);
+                }
+            }
+            output
+        }
+        Filter::Chain(ops) => {
+            let mut output = paths;
+            for op in ops.iter().rev() {
+                output = pull_limited(op, output, max_paths)?;
+                output = normalized_paths(output);
+                if output.len() > max_paths {
+                    return Err(SrcPathLimitExceeded);
+                }
+            }
+            output
+        }
+    };
+    let paths = normalized_paths(paths);
+    if paths.len() > max_paths {
+        return Err(SrcPathLimitExceeded);
+    }
+    Ok(paths)
+}
+
+fn pull(filter: &Filter, paths: Vec<Vec<String>>) -> Vec<Vec<String>> {
+    let paths = match filter {
+        Filter::Subdir(path) => paths
+            .into_iter()
+            .map(|suffix| join(path.segments(), &suffix))
+            .collect(),
+        Filter::Prefix(path) => paths
+            .into_iter()
+            .filter_map(|path_at_output| pull_prefix(path.segments(), &path_at_output))
+            .collect(),
+        Filter::Exclude(_) | Filter::Nop => paths,
+        Filter::Empty => Vec::new(),
+        Filter::Compose(members) => {
+            let mut output = Vec::new();
+            for member in members {
+                output.extend(pull(member, paths.clone()));
+                output = normalized_paths(output);
+            }
+            output
+        }
+        Filter::Chain(ops) => {
+            let mut output = paths;
+            for op in ops.iter().rev() {
+                output = normalized_paths(pull(op, output));
+            }
+            output
+        }
+    };
+    normalized_paths(paths)
+}
+
+fn pull_prefix(prefix: &[String], output: &[String]) -> Option<Vec<String>> {
+    if is_prefix(prefix, output) {
+        return Some(output[prefix.len()..].to_vec());
+    }
+    if is_prefix(output, prefix) {
+        return Some(Vec::new());
+    }
+    None
+}
+
+fn join(prefix: &[String], suffix: &[String]) -> Vec<String> {
+    prefix.iter().chain(suffix).cloned().collect::<Vec<_>>()
+}
+
+pub(crate) fn is_prefix(ancestor: &[String], descendant: &[String]) -> bool {
+    ancestor.len() <= descendant.len()
+        && ancestor
+            .iter()
+            .zip(descendant)
+            .all(|(left, right)| left == right)
+}
+
+pub(crate) fn display_path(path: &[String]) -> String {
+    if path.is_empty() {
+        "/".to_owned()
+    } else {
+        format!("/{}", path.join("/"))
+    }
+}
+
+pub(crate) fn path_segments(path: &str) -> Vec<String> {
+    path.strip_prefix('/')
+        .filter(|path| !path.is_empty())
+        .map(|path| path.split('/').map(ToOwned::to_owned).collect())
+        .unwrap_or_default()
+}
+
+pub(crate) fn all_compose_source_paths_limited(
+    filter: &Filter,
+    max_paths: usize,
+) -> Result<Vec<Vec<Vec<String>>>, SrcPathLimitExceeded> {
+    let mut groups = Vec::new();
+    collect_compose_source_paths_limited(filter, max_paths, &mut groups)?;
+    Ok(groups)
+}
+
+fn collect_compose_source_paths_limited(
+    filter: &Filter,
+    max_paths: usize,
+    groups: &mut Vec<Vec<Vec<String>>>,
+) -> Result<(), SrcPathLimitExceeded> {
+    match filter {
+        Filter::Compose(members) => {
+            let mut paths = Vec::new();
+            for member in members {
+                paths.extend(
+                    src_paths_limited(member, max_paths)?
+                        .into_iter()
+                        .map(|path| path_segments(&path)),
+                );
+            }
+            groups.push(paths);
+            for member in members {
+                collect_compose_source_paths_limited(member, max_paths, groups)?;
+            }
+        }
+        Filter::Chain(ops) => {
+            for op in ops {
+                collect_compose_source_paths_limited(op, max_paths, groups)?;
+            }
+        }
+        _ => {}
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        super::{canonicalize, parse, print},
+        *,
+    };
+
+    fn filter(text: &str) -> Filter {
+        canonicalize(parse(text).unwrap())
+    }
+
+    #[test]
+    fn invert_table() {
+        for (input, expected) in [
+            (":/p", ":prefix=p"),
+            (":prefix=p", ":/p"),
+            (":nop", ":nop"),
+            (":empty", ":empty"),
+            (":/a:prefix=x", ":/x:prefix=a"),
+            (
+                ":[:/a:prefix=x,:/b:prefix=y]",
+                ":[:/x:prefix=a,:/y:prefix=b]",
+            ),
+            (":exclude[::b/]", ":exclude[::b/]"),
+            (":/a:exclude[::b/]", ":exclude[::b/]:prefix=a"),
+        ] {
+            assert_eq!(print(&invert(&filter(input))), expected, "{input}");
+        }
+    }
+
+    #[test]
+    fn src_paths_examples() {
+        for (input, expected) in [
+            (":exclude[::secret]", vec!["/"]),
+            (":/a:exclude[::b/]", vec!["/a"]),
+            (":prefix=x", vec!["/"]),
+            (":/a:prefix=x", vec!["/a"]),
+            (":/a:[:/b:prefix=x,:/c:prefix=y]", vec!["/a/b", "/a/c"]),
+            (":[:/a:prefix=x,:/b:prefix=y]:/x", vec!["/a"]),
+            (":prefix=x:[:/w:prefix=b,:/z:prefix=a]", Vec::<&str>::new()),
+            (":exclude[::a]:/a", vec!["/a"]),
+            (":nop", vec!["/"]),
+            (":[:/B:prefix=b,:/a:prefix=a]", vec!["/B", "/a"]),
+            (":[:/a/b:prefix=x,:/a.c:prefix=y]", vec!["/a.c", "/a/b"]),
+        ] {
+            assert_eq!(src_paths(&filter(input)), expected, "{input}");
+        }
+    }
+}