diff --git a/.agent/HANDOFF.md b/.agent/HANDOFF.md index b431e7c..d096c68 100644 --- a/.agent/HANDOFF.md +++ b/.agent/HANDOFF.md @@ -2,187 +2,107 @@ ## 项目概览 -CMP 是使用 mcpp 构建的 C++23 Modules 协程运行时库,公开模块为 `mcpplibs.cmp`。 -v1 当前包含: +CMP 是使用 mcpp 构建的 C++23 Modules 协程运行时库,公开根模块为 `mcpplibs.cmp`。 +当前 v1 能力包括 `Task`、`RunLoop`、定时与协作取消、`when_all()`、`TaskGroup`、 +异步事件与互斥、固定大小 `ThreadPool`、`run_blocking()`,以及单 driver `IoContext`、 +数值地址 `TcpStream`/`TcpListener`。 -- 懒启动、单消费者 `Task`; -- 变参/vector `when_all()` 与静止点 `TaskGroup`; -- `OneShotEvent`、`AsyncManualResetEvent`、RAII `AsyncMutex`; -- 带定时和 `std::stop_token` 取消的调用线程 `RunLoop`; -- 固定大小 `ThreadPool` 与结构化同步调用隔离 `run_blocking()`; -- 单私有 I/O driver 的 `IoContext`、数值地址 TCP client `TcpStream`,以及数值地址 - TCP server `TcpListener`。 - -项目固定 mcpp `2026.8.28.1`、LLVM `22.1.8`、Asio `1.38.1` 与 gtest `1.15.2`。 -三平台 CI 引导 xlings 固定为 `2026.8.27.5`。`examples/basic` 是独立 path-dependency -consumer。 +包版本保持 `0.1.0`,项目固定 mcpp `2026.8.28.1`、LLVM `22.1.8`、Asio `1.38.1`、 +gtest `1.15.2`。DNS、TLS、UDP、detached task、自动取消传播、work stealing 与通用 I/O +不属于当前 v1 契约。 ## 当前目标与状态 -PR #10 已合并,`main` 已同步到 squash commit `9492075`。当前分支为 -`feature/phase6c-tcp-server-v1`。Phase 6C TCP Server v1 已通过全部本地门禁,核心实现提交 -为 `e0248ca`(`实现协程 TCP 服务端`),当前分支已推送至 `origin`。 - -Phase 7 是最后一个已规划的 v1 阶段,只做发布验收,不增加运行时 API。它的 Design/Plan -已完成复核,并已执行不依赖远程权限的早期包转换预检;正式实施仍等待 Phase 6C 合并后 -切换到独立分支。 - -用户已授权当前持续目标内的 Git commit 与 push。Phase 6C PR #11 已创建,Linux、macOS、 -Windows CI 均通过;合并仍需用户另行明确授权。 - -## 已完成工作 - -- 在现有 `mcpplibs.cmp:tcp` 分区增加 move-only `TcpListener`: - - `bind(IoContext&, Scheduler, numericAddress, port, stop_token)`; - - `accept(Scheduler, stop_token)`; - - `close()`、`is_open()`、`local_port()`。 -- bind/accept 保持懒执行;每个成功或错误都尝试通过调用方选择的返回 Scheduler 发布。 -- 支持数值 IPv4/IPv6、端口零、系统最大 backlog、一个 pending accept、取消后复用、 - 线程安全幂等 close,以及 listener 与已接受 `TcpStream` 的独立所有权。 -- `IoContext` 增加私有 listener 弱引用 registry;shutdown 先关闭 listener,再关闭 - stream,并排空 native handler 后 join driver。 -- accept 候选 socket 在 native initiation 前登记,并在返回 Scheduler 后复核待发布资源; - 自审同时纠正 bind/connect/accept 的 context shutdown 发布窗口,关闭获胜时返回 - `OperationCancelled`,不会发布已关闭对象。 -- read/write/accept 的 pending 标志是唯一重叠门禁;driver 可覆盖已完成 operation 的弱引用, - 不再错误依赖上一 Task 帧已经销毁。 -- 增加 21 项 Phase 6C TCP 测试;`tcp_test` 现为 45 项,完整套件为 10 个二进制、161 项。 -- readiness 的正常 TCP server 已从阻塞 POSIX socket 迁移到 - `TcpListener`/`TcpStream`;POSIX 只保留未监听失败端口构造。 -- 三种 README、三种架构文档、Phase 6C Design/Plan 和 readiness 报告已同步。 -- 新增并复核 Phase 7 v1 发布验收 Design/Plan,明确三平台双配置 CI、独立 consumer、 - 源码归档、mcpp-index Form A、GitHub Release 与各远程授权边界;Phase 7 后不自动规划 - Phase 8。 -- 预检纠正两项 mcpp `2026.8.28.1` 行为假设:生成的描述符不能直接作为 index 文件, - `--allow-dirty` 也不会把未提交工作树内容装入源码归档。 - -## 重要决策 - -- 只提供数值地址 bind;不隐藏阻塞 DNS。 -- port 0 交由系统选择,`local_port()` 返回实际端口;close 后保留最后绑定端口, - moved-from 返回 0。 -- v1 使用系统最大 backlog,不隐式设置 `reuse_address`,不开放任意 socket option。 -- 同一 listener 只允许一个 accepted-but-not-yet-published accept;连续服务由普通 accept - 循环与结构化 handler 组合。 -- pre/active accept cancellation 保持 listener 可用;listener close 或 context shutdown - 获胜时 pending accept 恰好以 `OperationCancelled` 完成一次。 -- 继续使用一个私有 I/O driver 和两类线性弱引用 registry;只有基准证明瓶颈后才扩展。 -- 不增加 DNS、TLS、UDP、endpoint 类型、超时、连接配额、detached handler、通用 I/O - 抽象或新依赖。 - -## 路线完整性审计 - -- 从 bootstrap、RunLoop、timer、cancellation、`when_all`、TaskGroup、events、AsyncMutex, - 到 Phase 4–7 及 CI 冷缓存修复,共有 16 组逻辑 Design/Plan;已逐一核对,全部成对存在。 -- Phase 4 已完成 v1 基础契约和 readiness;Phase 5 已完成 ThreadPool;Phase 6A 已完成 - blocking offload;Phase 6B 已完成 TCP client,并由 PR #10 三平台验证。 -- Phase 6C TCP server 的本地实现、161 项门禁和 PR #11 三平台 CI 均已完成,只待授权合并。 -- Phase 7 是最后一个计划阶段,仅做发布资格、三平台双配置、干净归档、GitHub Release 和 - mcpp-index 验收。没有遗漏的已规划 Phase 8;未来能力必须由真实需求启动独立 Design。 - -## 修改 / 重要文件 - -- 实现:`src/tcp.cppm` -- 测试:`tests/tcp_test.cpp` -- readiness consumer:`benchmarks/v1-readiness/src/main.cpp` -- readiness 数据:`docs/benchmarks/2026-08-29-cmp-v1-readiness.md` -- Design: - `docs/superpowers/specs/2026-08-30-cmp-phase6c-tcp-server-v1-design.md` -- Plan: - `docs/superpowers/plans/2026-08-30-cmp-phase6c-tcp-server-v1.md` +Phase 6C PR #11 已在 Linux x86_64、macOS arm64、Windows x86_64 全部通过后授权合并; +`main` 的对应 squash commit 为 `02cb6b9`。本地已从该提交创建 +`release/phase7-v1-release-qualification`。 + +Phase 7 是最后一个已规划的 v1 阶段,只做发布资格验收,不增加运行时 API。当前已完成 +本地实现、测试、readiness、早期源码归档和 Form A 描述符预检;Phase 7 项目 PR、远程 +三平台 CI、干净合并候选归档和公开发布仍未完成。验收门禁提交为 `941e42c` +(`完善 v1 发布验收门禁`),当前分支已推送并跟踪 +`origin/release/phase7-v1-release-qualification`。 + +Phase 7 PR #12 已获授权并创建。首轮 Windows CI 在真正编译测试前因 mcpp 已知 depfile +降级失败;根因修正提交 `b2c0911`(`修正 Windows 发布验收门禁`)已通过 Linux、macOS、 +Windows 三平台。PR 描述已获授权并修正为严格探针的真实语义,当前保持 OPEN、CLEAN、 +MERGEABLE,尚未获得合并授权。 + +用户已授权当前持续目标内的 Git commit 与 push。PR #12 的修改、PR 合并、tag、GitHub +Release、mcpp-index PR 和 index 合并仍必须按各自远程门禁单独授权。 + +## 本阶段修改 + +- 仅加强现有 `.github/workflows/ci-linux.yml`、`ci-macos.yml`、`ci-windows.yml`: + - Linux/macOS 根包运行严格、关闭缓存的 Dev/Release build 和 test; + - Windows 先运行严格探针,只允许已知 depfile 降级,再执行无 `--strict` 的同配置无缓存 + 完整 build/test; + - 独立 example 运行一次,并增加对应平台的无缓存 Release build。 +- 三种 README 与三种架构文档同步相同的本地验证命令和真实发布状态。 +- Phase 7 Design/Plan 记录已完成的本地证据和仍待完成的远程门禁。 +- 未修改运行时 API、源码、测试、版本、依赖或打包实现。 + +## 本地验证 + +- 本机 Linux 根包 Dev:`mcpp build --profile dev --strict --cache=off` 通过; + `mcpp test --profile dev --strict --cache=off` 为 10 个二进制、161/161 通过。 +- 根包 Release:`mcpp build --profile release --strict --cache=off` 通过; + `mcpp test --profile release --strict --cache=off` 为 10 个二进制、161/161 通过。 +- `examples/basic`:`mcpp run` 输出预期十行并退出 0;严格无缓存 Release build 通过。 +- readiness Release 连续五轮全部 PASS,每轮硬计数均为: + - compute:49,000 成功 / 1,000 预期失败 / 0 非预期失败; + - file I/O:1,000 / 100 / 0; + - network:20,000 / 100 / 0。 +- 五轮中位数:compute `38.475 ms / 1,299,546.0 ops/s`,file I/O + `217.363 ms / 5,060.7 ops/s`,network `2,622.017 ms / 7,665.9 ops/s`。 +- 三个 workflow 均通过 PyYAML 解析,并包含一致的发布资格流程。 +- `mcpp publish --dry-run --allow-dirty` 基于已提交的 Phase 6C 合并基线生成早期归档: + `cmp-0.1.0.tar.gz`,206,341 bytes,临时 SHA-256 + `fe36976fe76225f6121cce81ca22a1b2392a833795795fb9a00ed52d98dba4de`。 +- 临时描述符规范化为 namespace `mcpplibs`、原子包名 `cmp`、无内联 `mcpp` 段的 Form A + 后,`mcpp xpkg parse` 报告三平台 `0.1.0` 和 `parse OK`。 +- 解压后的早期源码归档使用已安装的 mcpp `2026.8.28.1` 完成 Dev/Release 严格无缓存 + 构建和 161/161 测试;归档内 example 运行和 Release build 也通过。 +- 本阶段没有源码或测试变更,按 Phase 7 规则无需新增 analyzer 检查。 +- 最终本地自审确认仅三个现有 workflow 与发布状态文档发生变化;三平台命令一致性、 + YAML 结构、CRLF 和 `git diff --check` 均通过。 +- Windows 严格探针通过 Bash 语法检查;在本机严格构建成功路径退出 0,合成日志验证精确 + 已知降级会放行、增加任意 warning 会失败,且临时日志由 trap 清理。 +- PR #12 的 `b2c0911` 三平台检查全部通过:Linux 2m53s、macOS 3m08s、Windows 5m22s。 + 完整日志确认每个平台的 Dev/Release 各为 10 个二进制、161/161,example 均输出预期十行 + 并完成 Release build;Windows 探针只出现已知 depfile warning 与对应 strict 汇总。 +- PR #12 描述已通过 GitHub REST 精确更新并回读比对,明确 Linux/macOS 严格门禁、Windows + 精确严格探针与无缓存完整门禁;未修改标题、分支或合并状态。 + +## 已知限制 + +- 早期归档只包含已提交的 `02cb6b9`,不包含当前未提交的 Phase 7 workflow/文档变更; + 正式 SHA 必须在 Phase 7 合并并同步干净 `main` 后重新生成。 +- mcpp `2026.8.28.1` 自动描述符的内联 `mcpp` 段缺少 `sources`,不能直接解析;index + 候选必须使用已验证的 Form A,且无真实 CN 镜像时保持普通字符串 URL。 +- 本机 `~/.mcpp` 的 vendored xlings `2026.8.11.2` 较旧且缺少 `subos_info`,因此显示 + runtime facts inconclusive 警告;构建、测试、示例和 readiness 均实际通过,未修改用户 + 全局环境。离开项目环境做归档验证时使用已安装的 mcpp `2026.8.28.1` 绝对路径。 +- readiness 性能仅是本机诊断数据,不是 CI 阈值或 SLA。 + +## 重要文件 + - Phase 7 Design: `docs/superpowers/specs/2026-08-30-cmp-phase7-v1-release-qualification-design.md` - Phase 7 Plan: `docs/superpowers/plans/2026-08-30-cmp-phase7-v1-release-qualification.md` +- CI:`.github/workflows/ci-linux.yml`、`ci-macos.yml`、`ci-windows.yml` - 用户文档:`README.md`、`README.zh.md`、`README.zh.hant.md` - 架构文档:`docs/architecture.md`、`docs/architecture.zh.md`、 `docs/architecture.zh.hant.md` -- 当前状态:`.agent/HANDOFF.md` - -## 验证情况 - -- `mcpp build --profile dev --strict --cache=off`:通过,LLVM `22.1.8`。 -- `mcpp test --profile dev --strict --cache=off`:10 个二进制、161/161 通过。 -- `mcpp build --profile release --strict --cache=off`:通过。 -- `mcpp test --profile release --strict --cache=off`:10 个二进制、161/161 通过。 -- `mcpp build --profile dist --strict --cache=off`:通过。 -- focused Release 发布窗口门禁连续 20 轮通过:bind、connect、accept 在返回 Scheduler - 阻塞期间遇到 context shutdown 均返回取消,未发布已关闭资源。 -- focused Release 原生 operation 复用门禁连续 5 轮、25 项执行全部通过,覆盖 - read/write/accept 的重叠拒绝与取消后复用。 -- Release `tcp_test` 使用随机顺序 seed `60830` 运行,45/45 通过,未发现用例顺序依赖。 -- 静态可移植性扫描确认 `src/`、`tests/`、`examples/` 未引入平台 socket 头或全局 - POSIX socket 调用;此类调用只存在于明确标注 POSIX-only 的 readiness consumer。 -- 基于 mcpp 生成的 26 条模块编译数据库运行 `clang-analyzer-*` 检查 - `src/tcp.cppm` 与 `tests/tcp_test.cpp`:两者退出码均为 0、无诊断。 -- stream pending read 与 listener pending accept 的并发 close 门禁在 Release 连续 100 轮 - 通过:合计 800 次并发 `close()` 均保持幂等,两类操作每轮都只取消完成一次。 -- focused Release listener 竞态连续 5 轮通过:共覆盖 100 次 close/accept 与 500 次 - stop/accept,均恰好产生一个合法结果。 -- focused Release 生命周期门禁连续 20 轮、共 100 项执行全部通过,覆盖 ThreadPool 返回、 - 失效返回 Scheduler、主动取消后复用、context shutdown 与 32 客户端负载。 -- 额外尝试的 Release TCP 全套 50 轮压力并未作为通过项:前 11 轮 43/43 全通过,随后本机 - 仅 `60700-61000` 的临时端口范围被短连接 TIME_WAIT 占满,port-0 bind 开始返回 - `Address already in use`;现场有 2,333 个 TIME_WAIT。未修改系统参数,也未让库隐式开启 - `reuse_address` 来掩盖资源耗尽。 -- TIME_WAIT 自然回落到 2 后,正常单轮 Release TCP 套件立即恢复为 43/43 通过,确认该失败 - 来自宿主端口资源压力,而非持续 socket 泄漏或实现状态损坏。 -- `examples/basic` 的 `mcpp run`:通过,既有十行输出正确,退出码 0。 -- `examples/basic` 的 `dist` 构建及生成二进制运行:通过,同样输出正确十行,退出码 0。 -- readiness Release 严格无缓存构建通过;最终 5 轮共 15 行场景全部 PASS,所有轮次硬计数均为: - - compute:49,000 成功 / 1,000 预期失败 / 0 非预期失败; - - file I/O:1,000 成功 / 100 预期失败 / 0 非预期失败; - - network:20,000 成功 / 100 预期失败 / 0 非预期失败。 -- 最终中位数:compute `25.443 ms / 1,965,140.8 ops/s`,file I/O - `147.661 ms / 7,449.5 ops/s`,native async TCP client/server - `2,239.147 ms / 8,976.6 ops/s`。 -- Phase 6C 当前工作树再次执行 Dev/Release 严格无缓存构建与测试,均为 10 个二进制、 - 161/161 通过;`src/tcp.cppm` 与 `tests/tcp_test.cpp` 的 `clang-analyzer-*` 再次退出 0、 - 无诊断;独立 example 再次正确输出十行并退出 0。 -- 当前 readiness 二进制重新连续运行 5 轮,所有轮次仍保持 compute - `49,000/1,000/0`、file I/O `1,000/100/0`、network `20,000/100/0` 的 - 成功/预期失败/非预期失败硬计数。 -- `mcpp publish --dry-run --allow-dirty` 成功生成早期归档 - `cmp-0.1.0.tar.gz`(184,046 bytes,SHA-256 - `08e467dfe45cfdddde3664be7223995b56c7e172a6c6e568ce7ae9f3da4db062`)与描述符。 - 该 SHA 只属于当前已提交基线,Phase 6C 合并后的最终归档必须重新生成。 -- 生成描述符直接解析会因内联 `mcpp` 段缺少 `sources` 失败;临时候选改为短包名 - `cmp` 并移除内联 `mcpp` 段后,`mcpp xpkg parse` 明确报告 Form A、三平台 - `0.1.0`、`parse OK`。 -- 早期源码归档不含 `TcpListener`,确认 `--allow-dirty` 未装入 Phase 6C。归档对应的 - Phase 6B 基线使用已安装的 mcpp `2026.8.28.1` 在隔离目录完成 Dev/Release 构建, - 两套均为 10 个测试二进制、140/140 通过;归档内 example 的运行和 Release 构建也通过。 -- PR #11 的 Linux x86_64、macOS arm64、Windows x86_64 检查均通过;首轮耗时分别为 - 2m43s、2m45s、2m49s。 - -## 已知问题 / 风险 - -- 本机 `~/.mcpp` 仍保存旧 vendored xlings `2026.8.11.2` 且缺少 `subos_info`; - mcpp 提示 runtime facts inconclusive,但当前 LLVM 双配置构建、测试、示例和 benchmark - 均成功。本阶段未修改用户全局环境。 -- 单 I/O driver 是 v1 简化;当前 readiness 只提供本机回归数据,不是 SLA。 -- 本机 IPv4 临时端口范围只有 301 个端口;不要连续重复完整 TCP 套件 50 轮。当前 5 轮竞态与 - 20 轮定向生命周期门禁是避免耗尽宿主资源的有界压力门。 -- bind 取消只在 driver setup 开始前协作生效;短同步 open/bind/listen 开始后由完成获胜。 -- 内置 RunLoop/ThreadPool 返回 Scheduler 会离开 I/O driver;自定义 Scheduler 必须自行提供 - 所需的线程转移语义,inline 实现不得在 driver continuation 中析构 `IoContext`。 -- listener 不提供 DNS、TLS、backlog 配置、socket option、多 pending accept 或自动 handler - 所有权;这些都需要具体 consumer 与独立设计。 -- 运行中的 blocking callable 仍不可抢占;ThreadPool 仍为无界共享 FIFO。 -- 离开项目本地 `.xlings` 环境后,普通 xlings shim 目前只激活 mcpp `2026.8.11.2`, - 无法解析 `.xlings.json` 要求的 `2026.8.28.1`;已安装的 `2026.8.28.1` 实际二进制可用, - 归档隔离构建用它完成。不要把本地 `.xlings` 目录塞进发布包;正式 CI/index consumer - 应按固定版本安装工具。 -- mcpp `2026.8.28.1` 自动描述符的内联 `mcpp` 段缺少 `sources`,且生成名是兼容全名; - index 候选必须规范化为短名 `cmp` 的 Form A。没有真实 CN 镜像时保留普通字符串 URL。 ## 剩余工作 -1. 用户审查三平台全绿的 PR #11,并明确授权后再合并。 -2. 合并后同步 `main`、新建 Phase 7 分支,按 Design/Plan 加强三平台 Dev/Release CI, - 并从干净候选重跑 161 项、example、readiness、归档及 Form A 验收。 -3. tag、GitHub Release、mcpp-index PR 与 index 合并均是独立远程操作,逐项等待授权。 +1. 合并前复核 PR #12 最新 HEAD 的三平台检查;获得单独授权后合并,同步干净 `main`, + 无 `--allow-dirty` 重新生成并验证正式归档。 +2. tag、GitHub Release、mcpp-index PR、index 合并和最终独立 consumer 验证按 Design 的 + 独立授权门禁逐项执行。 ## 推荐下一步 -由用户审查 PR #11 并确认是否授权合并;在此之前不执行 merge。 +停在 PR #12 合并门禁,等待用户明确授权。 diff --git a/.github/workflows/ci-linux.yml b/.github/workflows/ci-linux.yml index bb0b3e5..7738282 100644 --- a/.github/workflows/ci-linux.yml +++ b/.github/workflows/ci-linux.yml @@ -51,13 +51,15 @@ jobs: xlings install -y mcpp --version - - name: Build library - run: mcpp build - - - name: Run tests - run: mcpp test + - name: Qualify library + run: | + mcpp build --profile dev --strict --cache=off + mcpp test --profile dev --strict --cache=off + mcpp build --profile release --strict --cache=off + mcpp test --profile release --strict --cache=off - - name: Run example + - name: Qualify example run: | cd examples/basic mcpp run + mcpp build --profile release --strict --cache=off diff --git a/.github/workflows/ci-macos.yml b/.github/workflows/ci-macos.yml index b512808..ccde254 100644 --- a/.github/workflows/ci-macos.yml +++ b/.github/workflows/ci-macos.yml @@ -44,13 +44,15 @@ jobs: xlings install -y mcpp --version - - name: Build library - run: mcpp build - - - name: Run tests - run: mcpp test + - name: Qualify library + run: | + mcpp build --profile dev --strict --cache=off + mcpp test --profile dev --strict --cache=off + mcpp build --profile release --strict --cache=off + mcpp test --profile release --strict --cache=off - - name: Run example + - name: Qualify example run: | cd examples/basic mcpp run + mcpp build --profile release --strict --cache=off diff --git a/.github/workflows/ci-windows.yml b/.github/workflows/ci-windows.yml index 7b76dfa..eee543b 100644 --- a/.github/workflows/ci-windows.yml +++ b/.github/workflows/ci-windows.yml @@ -51,16 +51,34 @@ jobs: xlings install -y mcpp --version - - name: Build library + - name: Validate strict-mode degradation shell: bash - run: mcpp build + run: | + # mcpp 2026.8.28.1 的 Windows LLVM 后端暂不生成 depfile;只放行这一条已知降级。 + trap 'rm -f strict-mode.log' EXIT + set +e + mcpp build --profile dev --strict --cache=off --no-color > strict-mode.log 2>&1 + strict_status=$? + set -e + cat strict-mode.log + if [ "$strict_status" -ne 0 ]; then + test "$strict_status" -eq 1 + test "$(grep -Fc 'warning: this toolchain and platform combination emits no GNU depfile' strict-mode.log)" -eq 1 + test "$(grep -Fc 'error: 1 degradation(s) reported and --strict is set' strict-mode.log)" -eq 1 + test "$(grep -Ec '^(warning|error):' strict-mode.log)" -eq 2 + fi - - name: Run tests + - name: Qualify library shell: bash - run: mcpp test + run: | + mcpp build --profile dev --cache=off + mcpp test --profile dev --cache=off + mcpp build --profile release --cache=off + mcpp test --profile release --cache=off - - name: Run example + - name: Qualify example shell: bash run: | cd examples/basic mcpp run + mcpp build --profile release --cache=off diff --git a/README.md b/README.md index 57b8b20..4f1098c 100644 --- a/README.md +++ b/README.md @@ -414,17 +414,25 @@ after CMP has a stable runtime API worth demonstrating. ## Development -The local verification path is: +On Linux and macOS, the local verification path is: ```bash mcpp build --profile dev --strict --cache=off mcpp test --profile dev --strict --cache=off mcpp build --profile release --strict --cache=off mcpp test --profile release --strict --cache=off -cd examples/basic && mcpp run +cd examples/basic +mcpp run +mcpp build --profile release --strict --cache=off ``` -CI runs the equivalent build, test, and standalone example flow on Linux, macOS, and Windows. +On Windows, use the workflow's strict probe and remove `--strict` from the actual cache-off gates, +as described below. + +CI runs cache-off Dev/Release library gates, the standalone example, and its Release build on all +three platforms. Linux and macOS remain strict. With mcpp `2026.8.28.1`, Windows first uses a +strict probe that allows only the known LLVM depfile degradation, then performs the cache-off gates +without `--strict`; full rebuilds prevent that incremental limitation from reusing stale objects. The mcpp version is pinned by `.xlings.json`; contributors should not rely on an unrelated global mcpp installation. diff --git a/README.zh.hant.md b/README.zh.hant.md index e65babf..3db59a5 100644 --- a/README.zh.hant.md +++ b/README.zh.hant.md @@ -392,18 +392,24 @@ RunLoop 不是背景執行緒,也不會把阻塞程式碼自動變成非同步 ## 開發與驗證 -本機驗證路徑: +Linux 和 macOS 的本機驗證路徑: ```bash mcpp build --profile dev --strict --cache=off mcpp test --profile dev --strict --cache=off mcpp build --profile release --strict --cache=off mcpp test --profile release --strict --cache=off -cd examples/basic && mcpp run +cd examples/basic +mcpp run +mcpp build --profile release --strict --cache=off ``` -CI 在 Linux、macOS 和 Windows 上執行等價的建構、測試與獨立範例流程。mcpp 版本由 -`.xlings.json` 固定,不應依賴無關的全域 mcpp 安裝。 +Windows 應先使用 workflow 中的嚴格探針,並在實際無快取門禁中移除 `--strict`,原因見下文。 + +CI 在三個平台都執行無快取 Dev/Release 函式庫門禁、獨立範例及其 Release 建構;Linux 和 +macOS 保持嚴格模式。mcpp `2026.8.28.1` 在 Windows 上先執行嚴格探針,只放行已知的 LLVM +depfile 降級,再移除 `--strict` 執行無快取門禁;完整重建使這項增量限制無法沿用舊目的檔。 +mcpp 版本由 `.xlings.json` 固定,不應依賴無關的全域安裝。 CMP 目前不追蹤 `mcpp.lock`,`.gitignore` 明確執行這項儲存庫約定。執行期相依放在 `[dependencies]`,gtest 明確宣告在 `[dev-dependencies.compat]` 中。 diff --git a/README.zh.md b/README.zh.md index 972f8a4..f4a8988 100644 --- a/README.zh.md +++ b/README.zh.md @@ -392,18 +392,24 @@ RunLoop 不是后台线程,也不会把阻塞代码自动变成异步代码。 ## 开发与验证 -本地验证路径: +Linux 和 macOS 的本地验证路径: ```bash mcpp build --profile dev --strict --cache=off mcpp test --profile dev --strict --cache=off mcpp build --profile release --strict --cache=off mcpp test --profile release --strict --cache=off -cd examples/basic && mcpp run +cd examples/basic +mcpp run +mcpp build --profile release --strict --cache=off ``` -CI 在 Linux、macOS 和 Windows 上执行等价的构建、测试和独立示例流程。mcpp 版本由 -`.xlings.json` 固定,不应依赖无关的全局 mcpp 安装。 +Windows 应先使用 workflow 中的严格探针,并在实际无缓存门禁中去掉 `--strict`,原因见下文。 + +CI 在三个平台都执行无缓存 Dev/Release 库门禁、独立示例及其 Release 构建;Linux 和 macOS +保持严格模式。mcpp `2026.8.28.1` 在 Windows 上先运行严格探针,只放行已知的 LLVM depfile +降级,再去掉 `--strict` 执行无缓存门禁;完整重建使这一增量限制无法复用旧目标文件。mcpp +版本由 `.xlings.json` 固定,不应依赖无关的全局安装。 CMP 当前不跟踪 `mcpp.lock`,`.gitignore` 明确执行这一仓库约定。运行时依赖放在 `[dependencies]`,gtest 明确声明在 `[dev-dependencies.compat]` 中。 diff --git a/docs/architecture.md b/docs/architecture.md index 2604bde..f652778 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -497,7 +497,7 @@ Further partitions or implementation units are added only when another implement ## Verification -Run from the repository root: +Run from the repository root on Linux or macOS: ```text mcpp build --profile dev --strict --cache=off @@ -506,10 +506,12 @@ mcpp build --profile release --strict --cache=off mcpp test --profile release --strict --cache=off cd examples/basic mcpp run +mcpp build --profile release --strict --cache=off ``` -The expected result is a successful library build, 161 passing tests across ten binaries, and an -example that prints `Coroutine result: 42`, `Concurrent result: 42`, `Worker pool result: 42`, +The expected result is successful Dev/Release library and example builds, 161 passing tests across +ten binaries, and an example that prints `Coroutine result: 42`, `Concurrent result: 42`, +`Worker pool result: 42`, `Blocking result: 42`, `Task group result: 42`, `Recursive group result: 3`, `Event signalled`, `Reusable event cycles: 2`, `Mutex result: 42`, then `Coroutine cancelled` and exits with status 0. Tests retain the existing high-volume stack checks @@ -522,6 +524,8 @@ temporary-file, and loopback-network counts and throughput are recorded in the [v1 readiness benchmark](benchmarks/2026-08-29-cmp-v1-readiness.md). ThreadPool counts, concurrency, and five-round Release measurements are recorded in the -[ThreadPool benchmark](benchmarks/2026-08-29-cmp-thread-pool.md). The current Windows LLVM toolchain -does not emit GNU depfiles. If a file included by a module interface changes, an incremental build -can reuse an older BMI or object; `--cache=off` is used for a full local verification. +[ThreadPool benchmark](benchmarks/2026-08-29-cmp-thread-pool.md). On Windows, use the workflow's +strict probe and remove `--strict` from the actual cache-off gates. The current Windows LLVM toolchain +does not emit GNU depfiles. Its CI strict probe allows exactly that known degradation and rejects +any other warning or error; the actual Windows gates use `--cache=off` without `--strict`, so a full +rebuild cannot reuse an older BMI or object. diff --git a/docs/architecture.zh.hant.md b/docs/architecture.zh.hant.md index 313fcdf..5a410a0 100644 --- a/docs/architecture.zh.hant.md +++ b/docs/architecture.zh.hant.md @@ -466,7 +466,7 @@ OneShotEvent、AsyncManualResetEvent 與 AsyncMutex 已形成真實的公開邊 ## 驗證 -在儲存庫根目錄執行: +在 Linux 或 macOS 的儲存庫根目錄執行: ```text mcpp build --profile dev --strict --cache=off @@ -475,9 +475,11 @@ mcpp build --profile release --strict --cache=off mcpp test --profile release --strict --cache=off cd examples/basic mcpp run +mcpp build --profile release --strict --cache=off ``` -預期結果是函式庫建置成功、十個二進位檔中的 161 項測試全部通過,而且範例依序輸出 +預期結果是函式庫和範例的 Dev/Release 建置成功、十個二進位檔中的 161 項測試全部通過, +而且範例依序輸出 `Coroutine result: 42`、`Concurrent result: 42`、`Worker pool result: 42`、 `Blocking result: 42`、`Task group result: 42`、`Recursive group result: 3`、`Event signalled`、 `Reusable event cycles: 2`、 @@ -488,6 +490,7 @@ mcpp run 500 次 stop/accept 競態門檻;重點競態套件已連續執行多輪 Release 測試。計算、臨時檔案和回環 網路的成功/失敗計數及吞吐記錄在 [v1 可開發性壓測](benchmarks/2026-08-29-cmp-v1-readiness.md)。ThreadPool 的計數、並行和五輪 -Release 資料記錄在[執行緒池壓測](benchmarks/2026-08-29-cmp-thread-pool.md)。目前 Windows LLVM 工具鏈 -不會產生 GNU depfile;如果模組介面包含的檔案發生變更,增量建置可能沿用舊的 BMI 或 -目的檔。完整複驗時使用 `--cache=off`。 +Release 資料記錄在[執行緒池壓測](benchmarks/2026-08-29-cmp-thread-pool.md)。Windows 應使用 +workflow 中的嚴格探針,並在實際無快取門禁中移除 `--strict`。目前 Windows LLVM 工具鏈 +不會產生 GNU depfile;其 CI 嚴格探針只放行這一項已知降級,並拒絕其他 warning 或 error。 +實際 Windows 門禁使用 `--cache=off`,完整重建不會沿用舊的 BMI 或目的檔。 diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md index b0e2610..5764b26 100644 --- a/docs/architecture.zh.md +++ b/docs/architecture.zh.md @@ -463,7 +463,7 @@ OneShotEvent、AsyncManualResetEvent 与 AsyncMutex 已经形成真实的公共 ## 验证 -在仓库根目录执行: +在 Linux 或 macOS 的仓库根目录执行: ```text mcpp build --profile dev --strict --cache=off @@ -472,9 +472,11 @@ mcpp build --profile release --strict --cache=off mcpp test --profile release --strict --cache=off cd examples/basic mcpp run +mcpp build --profile release --strict --cache=off ``` -预期结果是库构建成功、十个二进制中的 161 项测试全部通过,并且示例依次输出 +预期结果是库和示例的 Dev/Release 构建成功、十个二进制中的 161 项测试全部通过,并且 +示例依次输出 `Coroutine result: 42`、`Concurrent result: 42`、`Worker pool result: 42`、 `Blocking result: 42`、`Task group result: 42`、`Recursive group result: 3`、`Event signalled`、 `Reusable event cycles: 2`、 @@ -485,6 +487,7 @@ mcpp run stop/accept 竞态门禁;重点竞态套件已连续执行多轮 Release 测试。 计算、临时文件和回环网络的成功/失败计数及吞吐记录在 [v1 可开发性压测](benchmarks/2026-08-29-cmp-v1-readiness.md)。ThreadPool 的计数、并发和五轮 -Release 数据记录在[线程池压测](benchmarks/2026-08-29-cmp-thread-pool.md)。当前 Windows LLVM 工具链不会 -生成 GNU depfile;如果模块接口包含的文件发生变化,增量构建可能复用旧的 BMI 或目标文件。 -完整复验时使用 `--cache=off`。 +Release 数据记录在[线程池压测](benchmarks/2026-08-29-cmp-thread-pool.md)。Windows 应使用 +workflow 中的严格探针,并在实际无缓存门禁中去掉 `--strict`。当前 Windows LLVM 工具链 +不会生成 GNU depfile;其 CI 严格探针只放行这一条已知降级,并拒绝其他 warning 或 error。 +实际 Windows 门禁使用 `--cache=off`,完整重建不会复用旧的 BMI 或目标文件。 diff --git a/docs/superpowers/plans/2026-08-30-cmp-phase7-v1-release-qualification.md b/docs/superpowers/plans/2026-08-30-cmp-phase7-v1-release-qualification.md index 1821e34..8ab7a52 100644 --- a/docs/superpowers/plans/2026-08-30-cmp-phase7-v1-release-qualification.md +++ b/docs/superpowers/plans/2026-08-30-cmp-phase7-v1-release-qualification.md @@ -2,7 +2,7 @@ **Date:** 2026-08-30 **Design:** `docs/superpowers/specs/2026-08-30-cmp-phase7-v1-release-qualification-design.md` -**Status:** Pending Phase 6C merge and authorized branch transition +**Status:** PR #12 open; three-platform qualification passed, merge and publication pending **Target package:** `mcpplibs.cmp` `0.1.0` ## Execution Rule @@ -44,9 +44,15 @@ Correct only factual mismatches. Edit only `.github/workflows/ci-linux.yml`, `ci-macos.yml`, and `ci-windows.yml` unless a proven platform defect requires a targeted source/test fix. -Replace the default-profile build/test steps with strict cache-off Dev and Release commands. Keep -the existing pinned bootstrap and platform runner choices. Run the example once and add its strict -cache-off Release build. +Replace the default-profile build/test steps with strict cache-off Dev and Release commands on +Linux and macOS. Keep the existing pinned bootstrap and platform runner choices. Run the example +once and add its cache-off Release build. + +On Windows, mcpp `2026.8.28.1` with LLVM reports the known missing-depfile degradation before tests +and `--strict` makes it fatal. Run one strict cache-off Dev probe and accept failure only when its +warning/error set exactly matches that single degradation. Then run the same cache-off Dev/Release +builds, all tests, example, and Release consumer build without `--strict`. Do not suppress output or +allow any other diagnostic. If a future mcpp fixes the degradation, the strict probe passes directly. Do not add a new workflow, matrix abstraction, benchmark job, cache service, sanitizer job, or floating dependency. @@ -56,7 +62,7 @@ review indentation and let GitHub Actions be the authoritative workflow parser. ## 4. Run local release qualification -From the repository root: +From the Linux qualification host's repository root: ```text mcpp build --profile dev --strict --cache=off @@ -127,7 +133,7 @@ Review every changed line for: - Windows shell/path assumptions; - claims ahead of evidence; - generated or local files entering release inputs; -- weakened test, strictness, or cache behavior; +- weakened tests, an unbounded strict-mode exception, or cache behavior; - remote steps that blur authorization boundaries. Run whitespace/encoding checks without changing unrelated CRLF files. Update `.agent/HANDOFF.md` @@ -172,4 +178,38 @@ a new independently reviewed Design. ## Completion Record -Pending. Fill this section only with commands and remote checks actually completed. +Local implementation record, 2026-08-30: + +- entry gate satisfied: Phase 6C PR #11 passed Linux, macOS, and Windows, merged with + authorization, and local `main` was synchronized to `02cb6b9` before creating + `release/phase7-v1-release-qualification`; +- release-surface audit found no public Asio leak, version drift, missing export, or unsupported + capability claim; +- the Linux and macOS workflows run strict cache-off Dev/Release root gates, the example, and its + Release build; Windows runs an exact allowlisted strict probe followed by matching cache-off + profiles without `--strict`; all three files parse as YAML; +- local Dev and Release root suites each passed 10 binaries and 161/161 tests; the example run and + Release build passed; +- five readiness rounds preserved compute `49,000/1,000/0`, file I/O `1,000/100/0`, and network + `20,000/100/0` success/expected-failure/unexpected-failure counts in every round; +- the committed Phase 6C package preflight produced a provisional 206,341-byte archive with + SHA-256 `fe36976fe76225f6121cce81ca22a1b2392a833795795fb9a00ed52d98dba4de`; +- its normalized Form A descriptor parsed, and the extracted archive passed strict cache-off Dev + and Release root builds and 161 tests, the example run, and its Release build; +- final local self-review confirmed that only the three existing workflows and release-state + documentation changed; YAML structure, command parity, CRLF, and `git diff --check` passed. + +Project PR #12 was created with authorization. Its first Windows run proved that a universal +`--strict` gate stops on mcpp's documented missing-depfile degradation before CMP tests execute; +that failed run is not release evidence. The extracted replacement probe passes syntax checking, +runs successfully when strict mode succeeds, accepts a synthetic exact known degradation, and +rejects a synthetic additional warning. + +Correction commit `b2c0911` then passed PR #12 on all three platforms: Linux x86_64 in 2m53s, +macOS arm64 in 3m08s, and Windows x86_64 in 5m22s. Log-level verification found two suites per +platform, each with 10 binaries and 161/161 tests, plus the expected ten-line example and Release +consumer build. Windows also completed the exact strict probe before its cache-off gates. + +PR #12 merge, the clean merged archive, tag, GitHub Release, mcpp-index PR, index CI/merge, and the +isolated indexed consumer check remain pending. Each remote mutation retains the authorization +boundary defined by the Design. diff --git a/docs/superpowers/specs/2026-08-30-cmp-phase7-v1-release-qualification-design.md b/docs/superpowers/specs/2026-08-30-cmp-phase7-v1-release-qualification-design.md index 140efdf..56f134c 100644 --- a/docs/superpowers/specs/2026-08-30-cmp-phase7-v1-release-qualification-design.md +++ b/docs/superpowers/specs/2026-08-30-cmp-phase7-v1-release-qualification-design.md @@ -1,9 +1,9 @@ # CMP Phase 7 v1 Release Qualification Design **Date:** 2026-08-30 -**Status:** Reviewed design; implementation waits for Phase 6C merge and a new branch +**Status:** PR #12 open; three-platform qualification passed, merge and publication pending **Package version:** `0.1.0` -**Baseline:** Phase 6C local tree, 161/161 Dev and Release tests +**Baseline:** Phase 6C PR #11 merged as `02cb6b9`, 161/161 Dev and Release tests ## Purpose @@ -19,7 +19,8 @@ not yet made the compatibility promise implied by semantic version `1.0.0`. Phase 7 includes only: - freezing the public API implemented through Phase 6C; -- strict cache-off Dev and Release CI on Linux x86_64, macOS arm64, and Windows x86_64; +- strict cache-off Dev and Release CI on Linux x86_64 and macOS arm64, plus an allowlisted strict + probe and full cache-off Dev/Release CI on Windows x86_64; - standalone path-consumer verification in Dev and Release configurations; - local readiness and release-package validation; - checking package metadata and the generated mcpp-index descriptor; @@ -41,6 +42,10 @@ Phase 7 implementation starts only after: The Design and Plan may exist before that gate. Runtime, CI, version, and release-file changes may not be mixed into the Phase 6C implementation branch. +The gate was satisfied on 2026-08-30: PR #11 passed Linux x86_64, macOS arm64, and Windows x86_64, +was merged with authorization, local `main` was fast-forwarded to `02cb6b9`, and the dedicated +Phase 7 branch was created. + ## Release Candidate Contract The release candidate exports the existing root module `mcpplibs.cmp` and keeps all current @@ -79,8 +84,8 @@ become package inputs. ## CI Qualification -Keep the three existing platform workflows and their current pinned xlings/mcpp environment. Each -workflow must execute the same release-relevant commands: +Keep the three existing platform workflows and their current pinned xlings/mcpp environment. +Linux and macOS execute these release-relevant commands: ```text mcpp build --profile dev --strict --cache=off @@ -92,6 +97,20 @@ mcpp run mcpp build --profile release --strict --cache=off ``` +The mcpp `2026.8.28.1` Windows LLVM backend intentionally reports `build/depfile` because it cannot +emit GNU depfiles. `--strict` converts that known incremental-build degradation into a fatal error +before the test suite runs. The Windows workflow therefore first executes a strict cache-off Dev +build as a probe. A failed probe is accepted only when its complete warning/error set is exactly +the single known depfile degradation and the corresponding strict-mode summary. It then executes +the same Dev/Release profiles and example flow without `--strict`, retaining `--cache=off` for every +explicit build/test gate. Any different strict diagnostic, compile failure, test failure, or example +failure remains fatal. A future mcpp version that fixes Windows depfiles makes the probe pass +directly without changing this workflow. + +This exception does not hide stale objects: cache-off qualification rebuilds from source, while the +shared manifest remains under strict validation on Linux and macOS. Requiring an impossible Windows +strict compile would test the build tool's documented limitation instead of CMP. + The example run remains the external import and runtime check. Its Release build adds a consumer configuration check without depending on an unstable generated executable path. @@ -144,6 +163,48 @@ The package manifest already owns that information. Do not add a second packager, release script, checked-in generated descriptor, or checked-in archive. mcpp already owns those transformations. +## Local Qualification Evidence + +The Phase 7 branch completed the local gates on 2026-08-30: + +- strict cache-off Dev and Release root builds passed; both suites ran 10 binaries and all + 161 tests passed; +- the standalone example ran with its expected ten lines and its strict cache-off Release build + passed; +- five Release readiness rounds preserved the exact hard counts in every round: compute + `49,000/1,000/0`, file I/O `1,000/100/0`, and network `20,000/100/0` for + success/expected failure/unexpected failure; +- the five-round medians were `38.475 ms / 1,299,546.0 ops/s` for compute, + `217.363 ms / 5,060.7 ops/s` for file I/O, and + `2,622.017 ms / 7,665.9 ops/s` for network; +- all three edited workflows parsed as YAML and contain matching profiles and cache-off gates; + Windows additionally contains the exact allowlisted strict probe described above; +- an early `mcpp publish --dry-run --allow-dirty` from committed merged Phase 6C produced + `cmp-0.1.0.tar.gz` (206,341 bytes, provisional SHA-256 + `fe36976fe76225f6121cce81ca22a1b2392a833795795fb9a00ed52d98dba4de`); +- the normalized temporary descriptor parsed as native-package Form A, and the extracted archive + passed strict cache-off Dev and Release root builds and all 161 tests, the example run, and its + Release build. + +That archive intentionally excludes the dirty Phase 7 workflow and documentation edits. It proves +the merged Phase 6C package contents and transformation only. The authoritative archive and hash +must be regenerated from clean merged Phase 7. No runtime source or test file changed in this local +qualification, so no new analyzer run was required. + +## Project PR Evidence + +PR #12 evaluated correction commit `b2c0911` on 2026-08-30 and passed all three workflows: + +- Linux x86_64 completed in 2m53s; +- macOS arm64 completed in 3m08s; +- Windows x86_64 completed in 5m22s, including the exact allowlisted strict probe. + +The complete logs show two suites per platform—Dev and Release—and every suite ran 10 test +binaries with 161/161 tests passing. Each platform also printed the expected ten-line example and +completed its Release consumer build. The Windows strict probe contained exactly the known missing +GNU depfile warning and its strict-mode summary; the following cache-off Dev/Release gates passed. +PR #12 remains open and merge authorization has not been granted. + ## Remote Release Boundary These are distinct, separately authorized remote operations: @@ -180,7 +241,8 @@ needed. Phase 7 is complete only when all of the following have authoritative evidence: 1. Phase 6C and Phase 7 PRs are merged without unresolved checks; -2. strict cache-off Dev and Release suites pass all 161 tests on Linux, macOS, and Windows; +2. strict cache-off Dev and Release suites pass all 161 tests on Linux and macOS; the allowlisted + Windows strict probe and cache-off Dev/Release suites pass all 161 tests; 3. the standalone example runs and its Release consumer build passes on all three platforms; 4. five final local readiness rounds have zero unexpected failures and exact hard counts; 5. the clean-tree publish dry-run succeeds; @@ -195,7 +257,7 @@ index-verified. ## Self-review Corrections -The reviews corrected seven likely scope errors: +The reviews corrected eight likely scope errors: 1. Keep `0.1.0`; a first usable capability set is not evidence for a `1.0.0` compatibility promise. 2. Reuse `mcpp publish --dry-run`; a custom release script or redundant checked-in descriptor adds @@ -209,7 +271,9 @@ The reviews corrected seven likely scope errors: 6. Treat mcpp's generated descriptor as a starting point, not index-ready truth: the pinned tool emits an invalid inline source segment and the index requires the atomic name plus Form A. 7. Do not mistake `--allow-dirty` for packaging dirty content. Its archive covers the committed - baseline, so final Phase 6C package evidence must wait for a clean merged candidate. + baseline, so final Phase 7 package evidence must wait for a clean merged candidate. +8. Do not require mcpp's known Windows LLVM depfile degradation to disappear. Allowlist it with an + exact strict probe, then use cache-off full builds; Linux and macOS retain strict manifest gates. ## Final Roadmap Boundary