mopr 0.0.69.dev0__tar.gz → 0.0.71.dev10__tar.gz

mopr-0.0.71.dev10/.gitee/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 提案流程与判定阈值（docs/proposals/README.md）
+    url: https://gitee.com/quant1x/mopr/blob/master/docs/proposals/README.md
+    about: 什么该走提案、编号与状态机、公示期与裁决规则
+  - name: 协作规范（CONTRIBUTING.md）
+    url: https://gitee.com/quant1x/mopr/blob/master/CONTRIBUTING.md
+    about: 命名与数据契约、文档与 AI 协同、Spec 驱动工作流、提交信息规范

mopr-0.0.71.dev10/.gitee/ISSUE_TEMPLATE/proposal.yml

@@ -0,0 +1,92 @@
+name: 提案（RFC）
+description: 提出跨语言语义 / 契约变更的提案（判定阈值与流程见 docs/proposals/README.md）
+title: "提案："
+labels: ["proposal"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        提交前请先看 [docs/proposals/README.md](https://gitee.com/quant1x/mopr/blob/master/docs/proposals/README.md) 的判定阈值：**跨语言语义 / 契约变更**才走提案，缺陷修复、单语言重构、纯文档改动请直接提 PR。
+        本 Issue 只收摘要，完整设计落在 `docs/proposals/<本 Issue 号>-<kebab-title>.md`（用 [0000-template.md](https://gitee.com/quant1x/mopr/blob/master/docs/proposals/0000-template.md)）。
+  - type: textarea
+    id: summary
+    attributes:
+      label: 摘要
+      description: 一句话说清要改什么、为什么现在提
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: 动机与现状落差
+      description: 现状如何、落差如何被感知、不改的代价（方案另在提案文件里展开）
+    validations:
+      required: true
+  - type: textarea
+    id: decisions
+    attributes:
+      label: 待决策项
+      description: 需要在提案中定案的开放问题，一条一行；未定案不得开工
+      placeholder: |
+        - tzdata 来源
+        - tzdata 缺失时的降级语义（报错 / 退回静态值）
+    validations:
+      required: true
+  - type: dropdown
+    id: kind
+    attributes:
+      label: 变更类型
+      options:
+        - 跨语言语义 / 接口变更
+        - 契约或数据字段命名变更
+        - 引入外部依赖 / 改变模块依赖现状
+        - 标杆实现替换
+        - 其它（在摘要中说明）
+    validations:
+      required: true
+  - type: input
+    id: languages
+    attributes:
+      label: 影响语言
+      description: 按语义顺序用半角逗号分隔，如 python,c++,rust,go
+      placeholder: python,c++,rust,go
+    validations:
+      required: true
+  - type: textarea
+    id: matrix
+    attributes:
+      label: 跨语言落地矩阵（摘要）
+      description: 逐语言写新增 / 变更符号与依赖变化；完整表落在提案文件第 6 节
+      placeholder: |
+        - Python（spec）：
+        - C++（生产）：
+        - Rust（扩展）：
+        - Go（扩展）：
+    validations:
+      required: true
+  - type: input
+    id: modules
+    attributes:
+      label: 关联模块与文档
+      placeholder: base/region（base/region.md §8.1）
+    validations:
+      required: true
+  - type: input
+    id: doc
+    attributes:
+      label: 提案文档路径
+      description: 取到本 Issue 号后改名并填此路径（编号即本 Issue 号）
+      placeholder: docs/proposals/<本 Issue 号>-xxx.md
+    validations:
+      required: false
+  - type: checkboxes
+    id: precheck
+    attributes:
+      label: 提交前自检
+      options:
+        - label: 已确认不属于"直接提 PR"的情形（单语言重构 / 缺陷修复 / 纯文档 / 单模块无争议新增）
+          required: true
+        - label: 已查看 docs/proposals/README.md §8 的现存提案清单，无重复提案
+          required: true
+        - label: 已知悉公示期为 7 天，且"无异议不等于采纳"
+          required: true

{mopr-0.0.69.dev0 → mopr-0.0.71.dev10}/.vscode-windows/settings.json

@@ -6,5 +6,6 @@
             "args": ["-NoExit", "-Command", "chcp 65001 > $null"]
         }
     },
-    "terminal.integrated.defaultProfile.windows": "PowerShell"
+    "terminal.integrated.defaultProfile.windows": "PowerShell",
+    "python-envs.defaultEnvManager": "ms-python.python:pyenv"
 }

{mopr-0.0.69.dev0 → mopr-0.0.71.dev10}/AGENTS.md

@@ -10,7 +10,7 @@ mopr 是单仓多语言库（monolibrary），同一语义将来可能有多种
 | --- | --- | --- |
 | Python | 3.12+ | 3.12.x |
 | C++ | C++20 | GCC 13+ / Clang 17+ / MSVC 14.3+ |
-| Rust | 1.98.0+ | 2024 edition |
+| Rust | 1.98.1+ | 2024 edition |
 | Go | 1.27+ | 1.27.x |
 | Java | 8+ | `pom.xml` 的 `java.version`（JDK 8 及以上） |
 
@@ -30,6 +30,7 @@ mopr 同一语义的多语言实现遵循固定的**角色与演进顺序**，
 
 - 文档、注释与 API 对照表描述语言时，遵循 `python → c++ → rust → go` 的演进顺序；**不得先入为主地以 C++ 为全部语言的语义源头**（反例：文档开头写"以 C++ 为基准 / 参考实现"）。语义判断以 Python（spec）为准绳。
 - 跨语言差异处理先从 Python（spec）侧定案，再推广至 C++（生产）与 Rust/Go（扩展）；若 Python 缺少某能力而其他语言已有，应先补 Python spec。
+- 同名语义的**命名与定名顺序**遵循 [「C++ 命名空间与头文件宏约定」](#c-命名空间与头文件宏约定)中的 snake_case 优先条款：语义名以 Python 为准，能蛇形的语言一律蛇形，Go / Java 保留本语言字形并在模块文档登记对应关系。
 - 语言最低版本表（上文）与 README.md「语言与版本要求」不因角色调整而改变。
 
 ## 文件命名与物理命名空间约定
@@ -62,6 +63,24 @@ mopr 同一语义的多语言实现遵循固定的**角色与演进顺序**，
 - `.cpp`、`tests/`、`benchmark/` 等不随安装分发的文件可用仓库根相对路径（构建期由 `$<BUILD_INTERFACE:${CMAKE_SOURCE_DIR}>` 提供 include 根）。
 - 使用方包含安装后的头文件写 `<mopr/<模块>/<头文件>.h>`（如 `<mopr/runtime/once.h>`）。
 
+## C++ 字符串处理复用约定
+
+- **写任何处理 `std::string` / `char` 的函数前，先查 `base/strings.h` 是否已有实现**；已有则一律复用，禁止在调用方（含各模块头文件内部）另写一份等价实现。
+- 常用对照（同目录头文件写 `#include "strings.h"`，其他目录写相对路径）：
+
+  | 需求 | 复用对象 |
+  | --- | --- |
+  | 切分（字符/子串分隔符） | `strings::split(str, delimiter, ignoreEmpty)`（token 会自动 `trim`） |
+  | 去首尾空白 / 去引号 | `strings::trim`、`strings::trim_view`、`strings::remove_quotes` |
+  | 大小写转换 | `strings::to_upper` / `strings::to_lower`（`std::string` 与 `std::string_view`）、`strings::to_upper(char)` / `to_lower(char)` |
+  | 全部替换 | `strings::replace_all` |
+  | 字符串 → 数值（要求整串消费） | `strings::try_parse<T>(str, out)`；允许失败取默认值时用 `strings::from_string<T>` |
+  | 数值 → 字符串 | `strings::to_string(value)` |
+  | 拼接 | `strings::join` |
+
+- 只有 `strings.h` 确实没有对应能力时（如位串渲染、base64 等编解码）才在本地实现，并在注释中说明为何不复用。
+- 复用 `strings.cpp` 中定义的函数（`split` / `replace_all` / `join` / `to_string` 重载等）会引入对 mopr 库的链接依赖，同一库内的头文件可接受（`encoding/csv.h` 即此用法）；若某头文件必须保持「仅头文件、零链接依赖」，则改用 `strings.h` 中 `inline` 的实现。
+
 ## C++ 命名空间与头文件宏约定
 
 - **命名空间**：以项目名 `mopr` 为根，**仓库根路径下的子目录为第二级**，多级目录依次下探：
@@ -73,16 +92,33 @@ mopr 同一语义的多语言实现遵循固定的**角色与演进顺序**，
   - `encoding/csv.h` → `MOPR_ENCODING_CSV_H`；`encoding/charsets.h` → `MOPR_ENCODING_CHARSETS_H`；
   - `distributed/id/hlc.h` → `MOPR_DISTRIBUTED_ID_HLC_H`；`base/strings.h` → `MOPR_BASE_STRINGS_H`。
 - 守卫宏与 `#pragma once` 并存；`#endif` 行以注释回写宏名（如 `#endif // MOPR_ENCODING_CSV_H`）。
+- **平台宏一律走 `base/feature_detection.h`**：C++ 侧**禁止**裸写 `_WIN32` / `__linux__` / `__APPLE__` / `_MSC_VER` / `__clang__` / `__aarch64__` / `_M_X64` 等编译器与平台原生宏，改用该头带 `MOPR_` 前缀的检测宏（`MOPR_OS_IS_WINDOWS` / `MOPR_OS_IS_LINUX` / `MOPR_OS_IS_APPLE` / `MOPR_COMPILER_IS_MSVC` / `MOPR_COMPILER_IS_CLANG` / `MOPR_COMPILER_IS_GNU_LIKE` / `MOPR_CPU_IS_X86_64` / `MOPR_CPU_IS_ARM_64` / `MOPR_ENDIAN_LITTLE` 等）。`base/feature_detection.h` 是全仓**唯一**允许裸写原生宏的文件（它必须，否则无从检测）；编译期能定的放这里，运行期收敛（函数包装）放 `base/platform.h`。理由：无前缀的 `OS_IS_*` / `TARGET_*` / `FORCE_INLINE` 与 Boost、Qt 等第三方存在撞名风险，且未定义宏在 `#if` 中静默求值为 0——拼错不报错、只会静默走错分支。
+  - 替换既有裸宏须逐处确认语义等价，**不可机械替换**：`defined(__GNUC__) && !defined(_MSC_VER)`（GNU 扩展属性是否可用）**不能**写成 `MOPR_COMPILER_IS_GCC`（会漏掉 clang，且在 clang-cl 下语义相反），应写 `MOPR_COMPILER_IS_GNU_LIKE`；只判 `MOPR_CPU_IS_ARM_64` 而漏掉编译器判断，会让 MSVC ARM64 误入 GNU 内联汇编分支。
 - 新增公共头文件一律遵循上述规则。既有不合规处按模块逐个收敛（`runtime::*` → `mopr::runtime::*`、`base/filesystem.h` 的 `filesystem` → `mopr::base::filesystem`、`base/except.h` 的 `quant1x` → `mopr::base`、`base/mmap.h` 的全局 `file_mmap` / `mmap_open` / `mmap_flush` / `mmap_close` → `mopr::base` 内的 `MmapHandle` / `mmap_open` / `mmap_flush` / `mmap_close`），不做一次性大范围改名。
 - **公开符号命名跨语言一致**（同一语义在各语言同名，便于跨语言对照与回溯）：
-  - **公开函数名一致**：Python 与 C++ 使用同一函数名（如 Python `mmap_open` ↔ C++ `mmap_open`），不因语言差异改名；Rust / Go 沿用本语言惯例的，须在模块文档的 API 对照表中给出对应关系。
+  - **snake_case 优先（铁律）**：只要目标语言允许小写蛇形，公开函数名就**必须**用 snake_case，**不得**用驼峰（lowerCamel / PascalCase）。此处"跨语言一致"指**语义名一致**，不是字形一致——**禁止**拿"要与某语言同名"当作 Python / C++ 保留驼峰的理由：
+    - Python（spec）与 C++（生产实现）一律 snake_case：`get_quarter_by_date` / `get_quarter_day` / `mmap_open`；
+    - Rust 同样 snake_case；
+    - Go / Java 受语言与生态规范限制无法小写蛇形（Go 导出标识符须大写开头，Java 方法为 lowerCamel），保留 PascalCase / lowerCamel，但语义名须与 Python / C++ **逐词对应**，并在模块文档的 API 对照表中登记对应关系（Go `GetQuarterByDate` ↔ Python / C++ `get_quarter_by_date`、Go `GetQuarterDay` ↔ `get_quarter_day`）；
+    - 反例（禁止）：C++ 写 `GetQuarterByDate` 并声称"与 Go 同名"；正确写法是 `get_quarter_by_date`，与 Go 的 `GetQuarterByDate` 语义对应。
+  - **语义名以 Python（spec）为准**：新语义先在 Python 定名，C++ / Rust / Go / Java 沿用其语义名，不在后续语言里另起名字；若某能力只在非 spec 语言存在，先补 Python spec 再推广（见「语言角色与演进顺序」）。
+  - **类型名不受此条约束**：类名 / 句柄类型 / RAII 类沿用各语言惯例（PascalCase，如 `MmapHandle` / `MappedMemory`），跨语言同名，见下文条款。
   - **函数名带模块前缀时不套同名命名空间**：函数名已含模块前缀（如 `mmap_`）时，C++ 侧不再套一层同名命名空间——`mmap_open` 直接位于 `mopr::base`，而非 `mopr::base::mmap::mmap_open`（同风格参考 `base/region.h` 的 `region_currency` / `region_timezone`）。
   - **公开结构体 typedef 统一 `mopr_` 前缀**：结构体标签与 typedef 用同名风格，如 `typedef struct mopr_xxx mopr_xxx_t;`；但跨语言共享的**句柄类型除外**——句柄跨语言同名，C++ 侧直接定义 `struct MmapHandle`（与 Python / Rust / Go 的 `MmapHandle` 一字不差），不套 `mopr_xxx_t` 风格。
   - **句柄类型不得命名 `File`**：句柄承载的是映射而不是文件（文件句柄只是其内部成员之一），`File` 会与 `os.File` / 文件流混淆；跨语言统一用 `MmapHandle`（C++ 为 `struct MmapHandle`）。
   - **句柄操作遵循语言惯例**：Python / Rust / Go 用句柄方法（`flush` / `close`、`Flush` / `Close`），C++ 句柄是 POD，用同名自由函数（`mmap_flush` / `mmap_close`）与之一一对应。
   - **同一语义可同时提供「公开 API + RAII 类」两层**：第一层为跨平台公开 API（如 `mmap_open` / `mmap_flush` / `mmap_close` + 句柄），资源由调用方显式管理；第二层为跨语言同名的 RAII 类（如 `MappedMemory`：`MappedMemory.open` 打开，析构 / `Drop` / `with` / `defer` 自动释放）。两层共用同一实现、语义必须一致，区别仅在释放时机；模块文档须给出两层对照表（示例见 `base/mmap.md`「1. 分层与命名」）。
   - **RAII 类名不得与模块名重复**：类名不叫 `mmap` / `Mmap`（与模块名、包名重复，且易被误读为句柄），统一用其语义名（如 `MappedMemory`），并跨语言同名；句柄另用 `XxxHandle`（如 `MmapHandle`，四语言同名，C++ 亦为 `struct MmapHandle`）。
-- 已知遗留（需按模块逐一评估，勿批量替换）：`base/common.h` 的全局 typedef 与常量（`i8` / `u8` / … 为标量别名、非结构体 typedef，不适用 `mopr_` 前缀约定），`base/format.h` 的全局探测模板与 `std::vector` 的 `operator<<`（依赖 ADL / 非限定查找，移入命名空间会导致使用方找不到），`tests/` 下 `*_test_types` 等测试辅助命名空间。
+- 已知遗留（需按模块逐一评估，勿批量替换）：`base/types.h` 的跨语言标量别名（`i8` / `u8` / … 为逐字符对齐 Rust 原生整型名而保留，是标量别名、非结构体 typedef，不适用 `mopr_` 前缀约定；由原 `base/common.h` 的全局 typedef 收敛而来，仅用于有 `.rs` 对照实现的模块，勿把现有 `int64_t` 批量改写为 `i64`），`base/format.h` 的全局探测模板与 `std::vector` 的 `operator<<`（依赖 ADL / 非限定查找，移入命名空间会导致使用方找不到），`tests/` 下 `*_test_types` 等测试辅助命名空间。
+
+## 测试规范
+
+系统级/底层组件（持久化、状态机、并发控制、底层资源管理等）的测试须遵循 [docs/system-component-testing-spec.md](docs/system-component-testing-spec.md)：
+
+- 覆盖六个维度：API 契约与边界防御、状态机生命周期、崩溃一致性与故障注入（**必选**）、不变量与属性测试、并发竞态、性能资源；
+- 测试以**不变量 (Invariants)** 为准绳，防御性优先于验证性，重点验证"失败时是否保持状态一致"；
+- 崩溃模拟必须用**进程级终止**（`os._exit` / `abort` / `kill -9`），不得用语言层异常或优雅退出替代；
+- 每个用例环境绝对隔离（独立临时目录/端口/内存空间），不依赖执行顺序。
 
 ## git 提交规范
 

{mopr-0.0.69.dev0 → mopr-0.0.71.dev10}/BUILDING.md

@@ -10,7 +10,7 @@ mopr 是单仓多语言库（monolibrary），同一语义提供 Python、C++、
 | C++ | 仓库根 `main.cpp`，`base/`、`runtime/`、`distributed/id/` 的 `*.cpp/*.h` | Conan 2 + CMake（当前构建主线） |
 | Rust | 仓库根 `Cargo.toml` / `lib.rs` / `main.rs`，`runtime/`、`distributed/` 的 `*.rs` | Cargo |
 | Go | `base/`、`runtime/`、`distributed/` 的 `*.go` | `go build ./...`（模块内多包，无独立 main） |
-| Java | `distributed/id/*.java`，测试/基准 `tests/runtime/*.java` | Maven（`mvn test` 运行 JUnit 5 测试/基准）/ javac |
+| Java | `distributed/id/*.java`，基准 `benchmark/micro/*.java` | Maven（`mvn test` 单元测试；`mvn -Pbench test` 运行 JUnit 5 基准）/ javac |
 
 ## 1. Python 构建
 
@@ -32,7 +32,7 @@ python -m mopr.log.core                          # 模块方式运行 (打印日
 
 也可不切换目录，显式挂载 `PYTHONPATH`：`$env:PYTHONPATH = "<仓库根>"; python -m mopr.log.core`。已 `pip install .` 的环境无此目录要求，常规导入即可。
 
-内置工具 `tools/`（`tools/license_header`、`tools/license_audit`）自洽、无跨子包相对导入，仓库根可直接顶层运行；等价于安装后的 `mopr.tools.*`（console script 为 `license-header`）：
+内置工具 `tools/`（`tools/license_header`、`tools/license_audit`）自洽、无跨子包相对导入，仓库根可直接顶层运行；等价于安装后的 `mopr.tools.*`（console script 为 `mopr-license-header`）：
 
 ```powershell
 python -m tools.license_header        # 仓库根 (源码形态)
@@ -490,7 +490,7 @@ use mopr::distributed;
 
 #### 3.5.2 安装
 
-前置：Rust 工具链可用（`cargo --version` 不低于本仓基线 1.98.0+，见 AGENTS.md）。三个外部工具都是 cargo 子命令插件，统一经 `cargo install` 编译安装到 `%USERPROFILE%\.cargo\bin`（rustup 通常已将该目录写入 PATH，新装后重开终端生效）：
+前置：Rust 工具链可用（`cargo --version` 不低于本仓基线 1.98.1+，见 AGENTS.md）。三个外部工具都是 cargo 子命令插件，统一经 `cargo install` 编译安装到 `%USERPROFILE%\.cargo\bin`（rustup 通常已将该目录写入 PATH，新装后重开终端生效）：
 
 ```powershell
 cargo install --locked cargo-deny
@@ -561,7 +561,7 @@ cargo cyclonedx -f json --spec-version 1.5   # 指定规范版本（支持 1.3 /
 
 ## 4. Java 构建
 
-Java 实现位于 `distributed/id/*.java`，测试/基准代码位于根目录 `tests/runtime/*.java`，与其它语言实现相互独立：不混入 Rust crate，也不参与 C++ 的 CMake/Conan 构建。
+Java 实现位于 `distributed/id/*.java`，基准代码位于基准套件目录 `benchmark/micro/*.java`（见 `benchmark/README.md`），与其它语言实现相互独立：不混入 Rust crate，也不参与 C++ 的 CMake/Conan 构建。单元测试与基准的编译/运行方式见 4.3。
 
 ### 4.1 编译
 
@@ -585,20 +585,40 @@ javac distributed\id\*.java
 java -cp build\java\classes io.github.quant1x.mopr.distributed.id.Generator
 ```
 
-### 4.3 测试与基准（JUnit 5）
+### 4.3 单元测试与基准
 
-根目录 `tests/runtime/LMAXDisruptorBenchmark.java` 是 Java 侧吞吐基准（LMAX
-Disruptor 环形缓冲对照，`@Test` 方法通过 JUnit 5 执行），声明于
-`pom.xml <dependencies>` 的 dev/test 依赖为 `junit-jupiter` 5.8.2 与
-`com.lmax:disruptor` 3.4.4（仅测试/基准使用，不随 `mopr` jar 分发的运行时；
-许可证与归档见 6 与 `THIRD_PARTY_NOTICES.md`「Java」节）。pom.xml 的
-surefire `<includes>` 已追加 `**/*Benchmark.java`（默认只收集 `*Test*` 命名），
-运行全部测试/基准：
+**单元测试**以 `tests/` 为测试源根（与 C++ / JS 测试同处跨语言测试目录），surefire 按
+默认命名 `Test*` / `*Test` / `*Tests` / `*TestCase` 收集：
 
 ```powershell
 mvn test
 ```
 
+**Java 基准**（`benchmark/micro/ringbuffer_LMAXDisruptorBenchmark.java`，LMAX Disruptor
+环形缓冲吞吐对照，场景参数与测量口径对齐 C++/Rust/Go 的 Vyukov MPMC 基准，`@Test`
+方法通过 JUnit 5 执行）与 C++ / Rust / Go 基准同处基准套件目录 `benchmark/`（见
+`benchmark/README.md`），但**不参与默认构建**：`benchmark/` 不是测试源根，默认
+`mvn test` 既不编译也不运行它，需要时用 `-Pbench` profile 显式开启：
+
+```powershell
+mvn -Pbench test                                            # tests/ 单元测试 + benchmark/ 基准
+mvn -Pbench test-compile                                    # 只编译基准（校验基准代码不腐烂）
+mvn -Pbench -Dtest=ringbuffer_LMAXDisruptorBenchmark test    # 只跑基准
+```
+
+隔离手段（JMH 等基准框架隔离的通用做法；本项目基准为手写 JUnit 5，未引入 JMH）：
+
+- **源隔离**：`-Pbench` 用 `build-helper-maven-plugin` 把 `benchmark/` 追加为「附加测试源根」
+  （`tests/` 仍是测试源根），基准类只落在 `build/java/test-classes`；主编译
+  （`default-compile`）、sources 与 javadoc 插件均排除 `benchmark/**` 与 `tests/**`
+  —— 基准源码不随 `mopr` jar / sources jar / javadoc jar 分发；
+- **依赖隔离**：声明于 `pom.xml <dependencies>` 的 `junit-jupiter` 5.8.2 与
+  `com.lmax:disruptor` 3.4.4 均标注 `<scope>test</scope>`，不进入 `mopr` jar，也不会作为
+  compile 依赖写进发布 pom 传递给下游（许可证与归档见 6 与 `THIRD_PARTY_NOTICES.md`「Java」节）；
+- **执行隔离**：默认 surefire 只收集单元测试命名；`-Pbench` 的 profile 配置完整列出
+  「单元测试命名 + `**/*Benchmark.java`」（profile 的 `includes` 会替换而非追加默认列表，
+  故需完整声明），保证一次跑齐单元测试与基准。
+
 ## 5. Go 构建
 
 > Go 实现为模块内多包形态（无独立可执行入口），代码位于 `base/`、`runtime/`、`distributed/` 下的 `*.go`（`go.mod`：`module github.com/quant1x/mopr`）；与 Python、C++（当前构建主线）、Rust、Java 各语言构建相互独立，不共享发布包。
@@ -647,7 +667,7 @@ Go 侧唯一运行时第三方依赖为 `golang.org/x/sys` v0.47.0（声明于 `
 - `third_party/licenses/`：许可证全文归档，按语言拆分 `third_party/licenses/python/`、`third_party/licenses/cpp/`、`third_party/licenses/rust/`、`third_party/licenses/go/`、`third_party/licenses/java/`；
 - `tools/license_audit/`：第三方依赖声明生成工具（`mopr.tools.license_audit`，仅 Python 标准库，仓库根执行），按语言子模块扫描依赖并刷新上述文件；
 - `THIRD_PARTY_TODO.md`（仓库根，运行期生成）：每次审计收尾把机器无法自动确定的事项（缺失许可证文本、新增组件版权/主页、许可类型未标注等）写入待办清单；无待办自动删除，不随版本控制（见 `.gitignore`），发布前必须清零；
-- Python 运行时第三方依赖目前仅 loguru（声明于 `pyproject.toml [project].dependencies`）：`python` 子命令核验声明与源码 import 交叉核对，并把许可证文本归档到 `third_party/licenses/python/`；Java 主代码（`distributed/id/`）仅 import JDK 内置包、`mopr` jar 运行时无第三方依赖，其 dev/test 依赖 junit-jupiter/disruptor（仅被 `tests/` 基准代码引用）由 `java` 子命令按源码引用证据推定角色并归档到 `third_party/licenses/java/`；Java 的 Maven 插件与 Python 的构建工具（build-system.requires）仅构建期使用，不随产物分发。
+- Python 运行时第三方依赖目前仅 loguru（声明于 `pyproject.toml [project].dependencies`）：`python` 子命令核验声明与源码 import 交叉核对，并把许可证文本归档到 `third_party/licenses/python/`；Java 主代码（`distributed/id/`）仅 import JDK 内置包、`mopr` jar 运行时无第三方依赖，其 dev/test 依赖 junit-jupiter/disruptor（仅被 `benchmark/` 基准代码引用）由 `java` 子命令按源码引用证据推定角色并归档到 `third_party/licenses/java/`；Java 的 Maven 插件与 Python 的构建工具（build-system.requires）仅构建期使用，不随产物分发。
 
 ### 6.1 文件与生成工具
 
@@ -657,7 +677,7 @@ Go 侧唯一运行时第三方依赖为 `golang.org/x/sys` v0.47.0（声明于 `
 | `cpp`（`tools/license_audit/handlers/cpp.py`） | `conan graph info` 解析依赖图（含 `tool_requires` 等闭包节点），把各组件许可证文件导出到 `third_party/licenses/cpp/<name>-<version>/` | 本机 conan 缓存（依赖需已解析 / 缓存，全程离线，不访问网络） |
 | `rust`（`tools/license_audit/handlers/rust.py`） | 解析 Rust 完整依赖闭包（基于 `Cargo.lock`，含传递依赖），自动刷新 `THIRD_PARTY_NOTICES.md` 的直接依赖表与闭包机器区段，并把各 crate 的许可证文件复制到 `third_party/licenses/rust/<crate>-<version>/` | 本地 cargo registry 源码缓存（先 `cargo build` / `cargo fetch` 即有） |
 | `go`（`tools/license_audit/handlers/go.py`） | go-licenses 的 `csv` / `save`：把各模块 `LICENSE` 文本归档到 `third_party/licenses/go/<模块路径>/` | Go 工具链 + go-licenses（PATH / GOBIN 找不到时自动 `go install github.com/google/go-licenses@latest`） |
-| `java`（`tools/license_audit/handlers/java.py`） | 解析 `pom.xml` 的 `<dependencies>`（Maven property 已展开），按源码引用证据推定角色：主代码（`base/`/`runtime/`/`distributed/`）引用的 compile/runtime 依赖为 direct，`tests/` 引用的（或 test/provided scope）为 dev/test；两类均从各构件 jar 内提取 LICENSE/COPYING/NOTICE 条目归档到 `third_party/licenses/java/<artifactId>-<version>/`（jar 内无许可证文本且无人工补录时按缺失待处理）；并扫描主代码与测试代码 import 提示未声明的第三方引用。当前声明的 dev/test 依赖：junit-jupiter 5.8.2（EPL-2.0，jar 内 `META-INF/LICENSE.md`）与 disruptor 3.4.4（Apache-2.0，jar 未随附许可证文件，已按官方全文人工补录） | 本机 maven 仓库 `~/.m2/repository`（依赖需已 `mvn test` / `mvn dependency:resolve`） |
+| `java`（`tools/license_audit/handlers/java.py`） | 解析 `pom.xml` 的 `<dependencies>`（Maven property 已展开），按源码引用证据推定角色：主代码（`base/`/`runtime/`/`distributed/`）引用的 compile/runtime 依赖为 direct，`benchmark/` 基准代码引用的（或 test/provided scope）为 dev/test；两类均从各构件 jar 内提取 LICENSE/COPYING/NOTICE 条目归档到 `third_party/licenses/java/<artifactId>-<version>/`（jar 内无许可证文本且无人工补录时按缺失待处理）；并扫描主代码与测试代码 import 提示未声明的第三方引用。当前声明的 dev/test 依赖：junit-jupiter 5.8.2（EPL-2.0，jar 内 `META-INF/LICENSE.md`）与 disruptor 3.4.4（Apache-2.0，jar 未随附许可证文件，已按官方全文人工补录） | 本机 maven 仓库 `~/.m2/repository`（依赖需已 `mvn test` / `mvn dependency:resolve`） |
 
 ### 6.2 运行示例（均为仓库根执行）