Metadata-Version: 2.4
Name: mopr
Version: 0.0.98
Summary: Monorepo Optimal Portable Runtime
Author: Quant1X
Author-email: Quant1X <wangfengxy@sina.cn>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/quant1x/mopr
Keywords: monorepo,portable-runtime,benchmark,performance
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: loguru>=0.7.3
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pandas>=2.1.0
Requires-Dist: python-dateutil>=2.9.0
Requires-Dist: lunardate>=0.2.2
Requires-Dist: tzlocal>=5.0
Requires-Dist: tzdata>=2024.1; platform_system == "Windows"
Requires-Dist: apscheduler~=3.11.3
Requires-Dist: PyYAML>=6.0
Requires-Dist: requests>=2.32.0
Requires-Dist: rich>=13.0
Requires-Dist: pydantic>=2.13
Requires-Dist: pdfminer.six>=20221105
Dynamic: license-file

# MOPR

> **单仓最优可移植运行时**
> *Monorepo Optimal Portable Runtime*
>
> 统一规范，基准驱动，**性能第一，正确与稳定是隐含前提**。
>
> 读作 *M-O-P-R*（或 *mopr*，/mɑpr/）。

---

## 项目简介

MOPR 是在统一规范约束下，以多轮基准测试为验证手段，从所有异构实现中筛选并维护性能最优运行时解的项目。它不是“基础库”，也不是“标准实现”——它的定位是**标杆实现**：为同一份规范下的其他实现提供可量化的性能参照与验证基准。

### 核心概念

| 概念 | 定义 | 职责 |
| --- | --- | --- |
| Spec | 规范 | 定义行为契约与接口边界，划定实现必须遵守的范围 |
| Benchmark | 基准测试 | 以多轮、多维度的量化测试验证实现，产出排名依据 |
| MOPR | 标杆实现 | 满足 Spec 与 Benchmark 验证的前提下，性能最优的实现 |

## 设计原则

### 1. 性能第一，正确与稳定是隐含前提

性能是优化方向与排名依据的第一优先级。正确性与稳定性并非与性能并列的取舍维度，而是参与性能排名的前置条件：不满足正确性与稳定性验证的实现，不具备参与性能排名的资格。

每一轮基准测试同时覆盖三个维度：

- **正确性**：输出是否符合 Spec 定义的行为契约
- **稳定性**：长时间运行、压力与边界条件下是否可靠
- **性能**：在前两者满足的前提下，是否达到最优

正确性与稳定性作为过滤条件，性能作为排序依据。

### 2. Spec 统一，实现自由

Spec 定义行为契约与接口边界。同一份规范下允许存在多种异构实现，MOPR 是其中经过多轮基准测试反复验证、在目标平台上始终正确且性能最优的实现，作为其他实现的对标基准。

### 3. 基准测试是设计驱动力

每个设计决策都必须回答一个问题：**该改动是否提升性能？** 其成立前提是不得破坏正确性与稳定性——若基准数据改善但正确性或稳定性测试失败，则该改动不成立。

### 4. 可移植性不等于性能下限

MOPR 在不同平台上分别追求该平台能达到的最高性能，而非让所有平台退化为同一套低性能通用实现。平台相关的极致优化是核心策略，但每份平台实现都必须先通过正确性与稳定性验证。

## 基准测试体系

基准测试套件按验证目标分为四类：

| 目录 | 类型 | 验证目标 |
| --- | --- | --- |
| `benchmark/micro/` | 微基准 | 吞吐、延迟、内存占用 |
| `benchmark/macro/` | 场景基准 | 端到端性能 |
| `benchmark/stability/` | 稳定性测试 | 长时间运行、压力、边界条件 |
| `benchmark/regression/` | 回归检测 | 性能劣化监测 |

只有通过正确性与稳定性验证的实现，其性能数据才纳入排名与对照。

## 项目结构

```
mopr/
├── spec/           # 规范定义
│   ├── api.md      # 接口契约
│   └── behavior.md # 行为语义
├── base/           # 基础组件：cache / mem / mmap / cron / timestamp ...
├── runtime/        # 运行时：ringbuffer / scheduler / once ...
├── distributed/    # 分布式：id（HLC / 生成器 / 状态存储）
├── encoding/       # 编码：csv / charsets / json / base64 / barcode ...
├── storage/        # 存储抽象
├── security/       # 安全：auth / audit / compliance
├── machine/        # 机器标识
├── log/            # 日志
├── data/           # 数据资产：contrib（外部数据源）/ meta（日历、场所）
├── meta/           # 元：asset_class（资产类别）/ calendar（交易日历）
├── benchmark/      # 基准测试套件
│   ├── micro/      # 微基准：吞吐、延迟、内存
│   ├── macro/      # 场景基准：端到端性能
│   ├── stability/  # 稳定性：长时间运行、压力、边界
│   └── regression/ # 性能回归检测
├── tests/          # 跨语言测试用例
├── docs/           # 设计决策记录
│   └── proposals/  # 提案（RFC）：跨语言语义 / 契约变更的决策过程
└── tools/          # 辅助工具（许可审计、许可证头、VS Code 配置分层同步）
```

**仓库根即实现根**：不设 `src/` 层，功能模块目录直接平铺在仓库根，同一功能的多语言实现共处同一目录、同名不同后缀（如 `base/mmap.py` / `base/mmap.h` / `base/mmap.rs` / `base/mmap/mmap.go`；各语言入口 `main.cpp` / `main.rs` 同样平铺在根）。

- **与 Go 的 package 对齐**：Go 的包边界以目录划分，功能模块目录因此与 Go 的 `package` 一一对应（`distributed/id` 即 `package id`）；C++ 命名空间第二级（`distributed/id/hlc.h` → `mopr::distributed::id`）、Python 子模块路径、Rust `mod` 路径均取自同一目录路径，保证同一功能在各语言的模块语义相同。
- **平台无关核心与平台极致优化就地组织**：核心语义落在各模块的公共实现中，平台相关优化留在同一模块内，按文件名后缀（`_posix` / `_windows` / `_unsupported`）或条件编译区分，不另设 `core/` / `platform/` 目录。

这些约定只服务一件事：**让同一语义在各语言占据同一位置**——看到 `mmap.py`，顺手就能看到 `mmap.h` / `mmap.rs` / `mmap/mmap.go`，跨语言对照不必先找路径。完整论证（层级为何由语言工具链决定、按语言分目录为何是反例、对 AI 的友好之处）见 [docs/directory-layout-rationale.md](docs/directory-layout-rationale.md)。

## 模块分层与分类

按工业管理视角，仓库根的一级目录分为以下 10 大类。功能模块直接平铺在仓库根（「仓库根即实现根」，见[项目结构](#项目结构)）；同一语义的多语言实现共处同一目录、同名不同后缀。各功能模块 README 以统一表格登记实现进度，表头顺序为 `功能 | python(spec) | c++ | rust | go | java | 说明`，图例：`✓` 已实现 · `部分` 部分实现（接口或覆盖有缺口） · `—` 未实现/待补。

### 1. 核心与包入口 (Core & Entry)

承载库的总入口与跨语言包映射，自身不含业务。

| 目录 | 角色 |
| --- | --- |
| `./` | `mopr` 顶层包入口，导出 `__version__`，承载跨语言 `package-dir` 映射 |
| `lib.rs` / `main.rs` / `main.cpp` | 跨语言库 / 可执行入口（仓库根文件） |

### 2. 标准语义抽象层 (Base — 非基础设施)

MOPR「多语言同语义、异构实现」设计原则的载体：把标准库中存在跨平台 / 跨编译器差异的部分抽象为统一语义、分别实现（如 C++ `chrono` 各 OS / 编译器差异）。**它不是基础设施**，而是 std 差异层的语义对齐层。

| 目录 | 包名 | 定位 | 实现梳理 |
| --- | --- | --- | --- |
| `base/` | `mopr.base` | chrono / time / crc32 / mmap / strings / filesystem / region … 等 std 差异层的跨语言统一语义 | [base/README.md](base/README.md) |

### 3. 基础设施 (Infrastructure — 与业务无关)

不直接服务于某业务域、为上层提供通用支撑的能力。

| 目录 | 包名 | 定位 | 实现梳理 |
| --- | --- | --- | --- |
| `encoding/` | `mopr.encoding` | 编码与序列化：charsets / csv / json / yaml / base64 | [encoding/README.md](encoding/README.md) |
| `config/` | `mopr.config` | 配置 | [config/README.md](config/README.md) |
| `log/` | `mopr.log` | 日志 | [log/README.md](log/README.md) |
| `runtime/` | `mopr.runtime` | 7×24 运行相关：once / ringbuffer / scheduler | [runtime/README.md](runtime/README.md) |
| `storage/` | `mopr.storage` | 存储抽象 / WAL（预写日志） | [storage/README.md](storage/README.md) |
| `machine/` | `mopr.machine` | 机器标识与本机信息采集 | [machine/README.md](machine/README.md) |
| `io/` | `mopr.io` | 网络 I/O 基础能力：HTTP、连接池与端点管理 | [io/README.md](io/README.md) |

### 4. 数据 / 领域 (Domain)

| 目录 | 包名 | 定位 | 实现梳理 |
| --- | --- | --- | --- |
| `data/` | `mopr.data` | 数据资产 / 读取 | — |
| `meta/` | `mopr.meta` | 资产类别 / 交易日历（只读字典） | [meta/README.md](meta/README.md) |

### 5. 分布式 (Distributed — 单独一类)

| 目录 | 包名 | 定位 | 实现梳理 |
| --- | --- | --- | --- |
| `distributed/` | `mopr.distributed`(`.id`) | HLC / 生成器 / 状态存储 / 状态锁 | [distributed/README.md](distributed/README.md) |

### 6. 安全与合规 (Security — 独立一类)

| 目录 | 包名 | 定位 | 实现梳理 |
| --- | --- | --- | --- |
| `security/` | `mopr.security`(`.auth`) | auth / audit / compliance，纯逻辑与 SPI | [security/README.md](security/README.md) |

### 7. 规范 / 契约层 (Spec)

| 目录 | 角色 |
| --- | --- |
| `spec/` | 跨模块契约：`api.md`（接口）/ `behavior.md`（行为）/ `README.md`（索引，只列契约与模块链接）；上提判据见 [spec/README.md](spec/README.md) |

### 8. 内置工具 (Tools)

| 目录 | 包名 | 定位 | 实现梳理 |
| --- | --- | --- | --- |
| `tools/` | `mopr.tools`(`.license_header` / `.license_audit` / `.vscode_sync`) | 版权头 / 许可证审计 / VS Code 配置同步 | [tools/README.md](tools/README.md) |

### 9. 测试与基准 (Test & Benchmark)

| 目录 | 角色 |
| --- | --- |
| `tests/` | 跨语言 C++ 测试用例 |
| `benchmark/` | micro / macro / stability / regression（验证目标见[基准测试体系](#基准测试体系)）|

### 10. 构建 / 发布 / 文档 / 第三方 (Build / Docs / Vendored)

| 目录 | 角色 |
| --- | --- |
| `cmake/` | CMake 片段 |
| `scripts/` | 脚本 |
| `test_package/` | Conan 测试包 |
| `third_party/` | vendored 第三方源码 |
| `docs/` | 设计决策记录与 proposals |
| `website/` | 项目站点 |
| `examples/` | 示例 |
| 仓库根文件 | `conanfile.py` / `CMakeLists.txt` / `CMakePresets.json` / `Cargo.toml`(`.lock`) / `go.mod`(`.sum`) / `pom.xml` / `rust-toolchain.toml` / `build-unix.sh` / `publish.*` / `refresh-clangd.*` |

## 语言与版本要求

MOPR 是单仓多语言库（monolibrary），同一份规范下将来会有多种语言实现。各语言的版本基线由本项目独立维护，不要求与同系列 `quant1x` 仓库同步：

| 语言 | 最低版本 | 推荐版本 |
| --- | --- | --- |
| Python | 3.12+ | 3.12.x |
| C++ | C++20 | GCC 14.2+ / Clang 19+（推荐 23+）/ MSVC 14.3+ |
| Rust | 1.98.1+ | 1.98.1+（2024 edition） |
| Go | 1.27+ | 1.27.x |
| Java | 8+ | JDK 8 及以上（见 `pom.xml` 的 `java.version`） |

- 当前仓库实现以 **C++20 + MSVC v143（Visual Studio 2022）+ CMake（≥3.25）/ Conan 2** 为主，构建细节见 [BUILDING.md](BUILDING.md)。
- C++ 编译器基线：GCC 取 **14.2+**（mingw-w64 16.2 / GCC 16.x 存在缺陷，退守 14.2、不使用 16.x）；**Clang 最低 19+（推荐 23+）、MSVC 14.3+ 不变**。注意：VS2022 自带的 LLVM 组件仅含 `clang-format`/`clang-tidy` 19.1.5，**不含 `clang`/`clang-cl` 编译器本体**，编译请以独立安装的 LLVM ≥19（推荐 23+）为准。
- 后续新增 Python / Rust / Go / Java 实现时，须遵循上表最低版本基线，不得使用低于基线的语言特性与 API；版本表变更由本项目独立评估。

## 快速开始

当前 C++ 工程（CMake + Conan 2）的构建与编译步骤见 [BUILDING.md](BUILDING.md)。

```text
// TODO: 基准运行示例，待接口定义完成后补充
```

## 项目状态与路线图

🚧 早期阶段 — 实现逐模块推进中，Spec 随多语言落地结晶上提。

当前推进顺序：

1. 起草 Spec：确定 `spec/api.md`（接口契约）与 `spec/behavior.md`（行为语义）—— 契约从**已落地且已被验证**的多语言实现结晶上提，判据见 [spec/README.md](spec/README.md)「4. 契约上提判据」
2. 搭建基准测试套件与验证流程
3. 基于平台无关核心实现首个基准实现
4. 开展平台相关优化，并逐平台完成正确性、稳定性与性能验证

## License / 协议

本项目采用 **GNU Affero General Public License v3**（[AGPL-3.0](LICENSE) / SPDX: `AGPL-3.0-only`）授权。

- 允许自由使用、复制、修改与再分发，但派生作品必须同样以 AGPLv3 发布（强 Copyleft）。
- 通过网络提供服务的修改版本（含远程交互）须按第 13 条向用户开放对应源码。
- 完整条款见根目录 [LICENSE](LICENSE) 文件。

Copyright (C) 2026 Quant1X <wangfengxy@sina.cn>
